/* A component with functionality given in Java.
Copyright (c) 1997-2014 The Regents of the University of California.
All rights reserved.
Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the above
copyright notice and the following two paragraphs appear in all copies
of this software.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
ENHANCEMENTS, OR MODIFICATIONS.
PT_COPYRIGHT_VERSION_2
COPYRIGHTENDKEY
*/
package ptolemy.component;
import ptolemy.data.TupleToken;
import ptolemy.kernel.ComponentEntity;
import ptolemy.kernel.CompositeEntity;
import ptolemy.kernel.Port;
import ptolemy.kernel.util.IllegalActionException;
import ptolemy.kernel.util.NameDuplicationException;
///////////////////////////////////////////////////////////////////
//// AtomicComponent
/**
A component with functionality given in Java. The functionality can
be given in the {@link #run()} method or by the
{@link MethodCallPort#call(TupleToken)} method of contained ports
that are providers.
@author Yang Zhao
@version $Id: AtomicComponent.java 70402 2014-10-23 00:52:20Z cxh $
@since Ptolemy II 10.0
@Pt.ProposedRating yellow (ellen_zh)
@Pt.AcceptedRating red (cxh)
*/
public class AtomicComponent extends ComponentEntity implements Component {
/** Construct an entity with the given name contained by the specified
* entity. The container argument must not be null, or a
* NullPointerException will be thrown. This entity will use the
* workspace of the container for synchronization and version counts.
* If the name argument is null, then the name is set to the empty string.
* Increment the version of the workspace.
* This constructor write-synchronizes on the workspace.
* @param container The container entity.
* @param name The name of the entity.
* @exception IllegalActionException If the entity cannot be contained
* by the proposed container.
* @exception NameDuplicationException If the name coincides with
* an entity already in the container.
*/
public AtomicComponent(CompositeEntity container, String name)
throws IllegalActionException, NameDuplicationException {
super(container, name);
setContainer(container);
_addIcon();
}
///////////////////////////////////////////////////////////////////
//// public methods ////
/** Initialize the component, which in this base class means
* doing nothing and returning immediately. This is invoked once after
* preinitialize() and again whenever the component needs
* to be reinitialized.
* @exception IllegalActionException If initialization
* cannot be completed (not thrown in this base class).
*/
@Override
public void initialize() throws IllegalActionException {
}
/** Create a new port with the specified name.
* The container of the port is set to this entity.
* This overrides the base class to create an instance of MethodCallPort.
* Derived classes may override this to further constrain the ports.
* This method is write-synchronized on the workspace and increments
* its version number.
* @param name The new port name.
* @return The new port
* @exception IllegalActionException If the argument is null.
* @exception NameDuplicationException If this entity already has a
* port with the specified name.
*/
@Override
public Port newPort(String name) throws IllegalActionException,
NameDuplicationException {
try {
_workspace.getWriteAccess();
Port port = new MethodCallPort(this, name);
return port;
} finally {
_workspace.doneWriting();
}
}
/** Preinitialize the component, which in this base class means doing
* nothing and returning immediately. This is invoked exactly
* once per execution of a model, before any other methods
* in this interface are invoked.
* @exception IllegalActionException If preinitialization
* cannot be completed (not thrown in this base class).
*/
@Override
public void preinitialize() throws IllegalActionException {
}
/** Execute the component, which in this base class means doing
* nothing and returning immediately.
* This is invoked after preinitialize()
* and initialize(), and may be invoked repeatedly.
* @exception IllegalActionException If the run cannot be completed
* (not thrown in this base class).
*/
@Override
public void run() throws IllegalActionException {
}
/** Wrap up an execution, which in this base class means doing
* nothing and returning immediately. This method is invoked
* exactly once per execution of a model. It finalizes
* an execution, typically
* closing files, displaying final results, etc. If any other
* method from this interface is invoked after this, it must
* begin with preinitialize().
* @exception IllegalActionException If wrapup fails.
*/
@Override
public void wrapup() throws IllegalActionException {
}
///////////////////////////////////////////////////////////////////
//// protected methods ////
/** Add a port to this entity. This overrides the base class to
* throw an exception if the added port is not an instance of
* MethodCallPort. This method should not be used
* directly. Call the setContainer() method of the port instead.
* This method does not set
* the container of the port to point to this entity.
* It assumes that the port is in the same workspace as this
* entity, but does not check. The caller should check.
* Derived classes may override this method to further constrain to
* a subclass of MethodCallPort.
* This method is not synchronized on the workspace, so the
* caller should be.
* @param port The port to add to this entity.
* @exception IllegalActionException If the port class is not
* acceptable to this entity, or the port has no name.
* @exception NameDuplicationException If the port name collides with a
* name already in the entity.
*/
@Override
protected void _addPort(Port port) throws IllegalActionException,
NameDuplicationException {
if (!(port instanceof MethodCallPort)) {
throw new IllegalActionException(this, port,
"Incompatible port class for this entity.");
}
super._addPort(port);
}
///////////////////////////////////////////////////////////////////
//// private methods ////
private void _addIcon() {
_attachText("_iconDescription", "\n");
}
}