001/* A contract for dynamic providers of actor-oriented classes.
002
003Copyright (c) 2015-2016 The Regents of the University of California.
004All rights reserved.
005
006Permission is hereby granted, without written agreement and without
007license or royalty fees, to use, copy, modify, and distribute this
008software and its documentation for any purpose, provided that the above
009copyright notice and the following two paragraphs appear in all copies
010of this software.
011
012IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA LIABLE TO ANY PARTY
013FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016SUCH DAMAGE.
017
018THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023ENHANCEMENTS, OR MODIFICATIONS.
024
025PT_COPYRIGHT_VERSION_2
026COPYRIGHTENDKEY
027*/
028
029package org.ptolemy.classloading;
030
031import org.ptolemy.commons.VersionSpecification;
032
033import ptolemy.kernel.CompositeEntity;
034
035/**
036 * A contract for dynamic providers of actor-oriented classes, i.e. reusable assemblies of model elements.
037 * <p>
038 * These providers could obtain such assemblies from moml class definitions in files, databases or other storage systems,
039 * or defined in any relevant manner.
040 * </p>
041 * <p>
042 * Implementations should typically be injected in a ClassLoadingStrategy.
043 * Currently the OSGiClassLoadingStrategy is the main injection target.
044 * </p>
045 *
046 * @author ErwinDL
047 * @version $Id$
048 * @since Ptolemy II 11.0
049 * @Pt.ProposedRating Yellow (ErwinDL)
050 * @Pt.AcceptedRating Yellow (ErwinDL)
051 */
052public interface ActorOrientedClassProvider {
053
054    /**
055     * Returns the <code>CompositeEntity</code> providing the requested actor-oriented class definition, if this provider has it.
056     * <p>
057     * An actor-oriented class can have only a "simple" name, i.e. no dots, as the underlying <code>NamedObj</code> does not allow dot-separated names.
058     * However, provider implementations may allow <code>className</code> values with dots.
059     * Remark that once loaded in the Ptolemy runtime, all actor-oriented classes are managed by their "simple" name only!
060     * So, when using dot-separated "nested" names, the final part must still be unique within the complete runtime!
061     * </p>
062     * <p>
063     * So using hierarchical class names may make sense to support organizing the classes in hierarchical structures for storage and lookup,
064     * instead of being limited to simple "linear" lists. But they do not introduce a runtime "name space" like packages do for Java classes.
065     * </p>
066     * If this provider doesn't have this class available, it should throw a <code>ClassNotFoundException</code>.
067     * (Optionally, it could also just return null, for those dvp-ers who don't like exceptions. ;-) )
068     *
069     * @param className Mandatory, not-null.
070     * @param versionSpec optional constraint on desired version for the class that must be provided. If null, no version constraint is imposed.
071     * @return the actor-oriented class matching the given className
072     * @exception ClassNotFoundException if this provider can not provide the requested class for the requested version (if specified)
073     */
074    CompositeEntity getActorOrientedClass(String className,
075            VersionSpecification versionSpec) throws ClassNotFoundException;
076}