Package org.terraswarm.accessor

Class JSAccessor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Placeable, Initializable, AccessorOrchestrator, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class JSAccessor
extends JavaScript
    An component accessor that consists of an interface and a script.

    The "Vision of Swarmlets" paper defines three types of accessors: Interface, Component and Composite. The paper states: "A component accessor has an interface and a script... The script defines one or more functions that are invoked by the swarmlet host."

    This is a specialized JavaScript actor that hides the script from casual users by putting it in "expert" mode. It also sets the actor to "restricted" mode, which restricts the functionality of the methods methods and variables provided in the JavaScript context.

    FIXME: This should support versioning of accessors. It should check the accessorSource for updates and replace itself if there is a newer version and the user agrees to the replacement. This will be tricky because any parameters and connections previously set should be preserved.

    This actor extends JavaScript and thus requires Nashorn, which is present in Java-1.8 and later.

    This actor will run git and node, which require network access. To skip running things that require network access, set the PT_NO_NET environment variable to a non-empty string. For example, under bash:

       export PT_NO_NET=true

    Note that if PT_NO_NET is set to any value, then the actor will attempt to avoid using the network.

    To always run ptdoc, set the PT_RUN_PTDOC environment variable. Otherwise, if PT_NO_NET is not set, then the ptdocs are only regenerated when the git pull modifies a file.

    References

    Elizabeth Latronico, Edward A. Lee, Marten Lohstroh, Chris Shaver, Armin Wasicek, Matt Weber. A Vision of Swarmlets, IEEE Internet Computing, Special Issue on Building Internet of Things Software, 19(2):20-29, March 2015.

    Since:
    Ptolemy II 11.0
    Version:
    $Id$
    Author:
    Edward A. Lee, Contributor: Christopher Brooks
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (eal)

    • Field Detail

      • checkoutOrUpdateAccessorsRepository

        public SharedParameter checkoutOrUpdateAccessorsRepository
        If true, then check out the accessors git repository when the accessor is reloaded and run ant to build the PtDoc files. This repository is not currently publically readable. This parameter is a boolean, and the initial default value is true. This parameter is a shared parameter, meaning that changing it for any one instance in a model will change it for all instances in the model.

    • Method Detail

      • accessorToMoML

        public static java.lang.String accessorToMoML​(java.lang.String urlSpec)
                                       throws java.io.IOException,
                                              javax.xml.transform.TransformerConfigurationException,
                                              IllegalActionException
        Generate MoML for an Accessor.

        The MoML is wrapped in <entity></entity> and suitable for handleAccessorMoMLChangeRequest().

        The accessor is read in from a url, processed with XSLT and MoML is returned.

        In this method, the value of the checkoutOrUpdateRepository parameter is honored.

        Parameters:
        urlSpec - The URL of the accessor.
        Returns:
        MoML of the accessor, which is typically passed to handleAccessorMoMLChangeRequest().
        Throws:
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.
        IllegalActionException - If no source file is specified.

      • accessorToMoML

        public static java.lang.String accessorToMoML​(java.lang.String urlSpec,
                                              boolean obeyCheckoutOrUpdateRepositoryParameter)
                                       throws IllegalActionException,
                                              java.io.IOException,
                                              javax.xml.transform.TransformerConfigurationException
        Generate MoML for an Accessor.

        The MoML is wrapped in <entity></entity> and suitable for handleAccessorMoMLChangeRequest().

        The accessor is read in from a url, processed with XSLT and MoML is returned.

        Parameters:
        urlSpec - The URL of the accessor.
        obeyCheckoutOrUpdateRepositoryParameter - If true, then use the value of the checkoutOrUpdateRepository parameter. If false, then override the value of the checkoutOrUpdateRepository parameter and do not checkout or update the repository or invoke JSDoc. During testing, this parameter is set to false after the first reload of an accessor so as to improve the performance of the tests.
        Returns:
        MoML of the accessor, which is typically passed to handleAccessorMoMLChangeRequest().
        Throws:
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.
        IllegalActionException - If no source file is specified.

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone the actor into the specified workspace.
        Overrides:
        clone in class JavaScript
        Parameters:
        workspace - The workspace for the new object.
        Returns:
        A new actor.
        Throws:
        java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.
        See Also:
        Object.clone()

      • createSymbolicLinks

        public static java.lang.String createSymbolicLinks()
                                            throws java.io.IOException
        Create symbolic links for the modules.
        Returns:
        messages about creating the links.
        Throws:
        java.io.IOException - If there is a problem creating a link.

      • getAccessorsRepository

        public static void getAccessorsRepository()
                                   throws java.io.IOException
        Check out or update the accessor repository, unless the checkoutOrUpdateAccessorsRepository parameter is false, in which case, do nothing. If the upate succeeds, and the response from the git server does not include "At revision ", then also run ant in the accessors/web directory to update the documentation. If the checkout or update fails once, the it will not be tried again until the JVM is restarted.
        Throws:
        java.io.IOException - If the repository cannot be checked out.

      • getLocalURL

        public static java.net.URL getLocalURL​(java.lang.String urlSpec,
                                       java.net.URL accessorOrPtDocURL)
                                throws java.io.IOException,
                                       java.net.MalformedURLException
        If the URL can be found locally, return it, otherwise return the value of the passed in URL.
        Parameters:
        urlSpec - The String URL of the accessor or *PtDoc.xml file.
        accessorOrPtDocURL - The proposed URL of the accessor or *PtDoc.xml file.
        Returns:
        If the urlSpec matches https*://(www\.)*icyphy.org/accessors and the corresponding file can be found in the directory returned by _accessorDirectory(), then return a URL that refers to the local file. Otherwise, return the value of the accessorOrPtDocURL argument.
        Throws:
        java.io.IOException - If thrown while getting the accessor directory.
        java.net.MalformedURLException - if throw while creating a URL.

      • handleAccessorMoMLChangeRequest

        public static void handleAccessorMoMLChangeRequest​(java.lang.Object originator,
                                                   java.lang.String urlSpec,
                                                   NamedObj context,
                                                   java.lang.String changeRequest,
                                                   double x,
                                                   double y)
        Handle an accessor-specific MoMLChangeRequest. In the postParse() phase, the _location and accessorSource attributes are updated.
        Parameters:
        originator - The originator of the change request.
        urlSpec - The URL string specification.
        context - The context in which the actor is created.
        changeRequest - The text of the change request, typically generated by accessorToMoML(String).
        x - The x-axis value of the actor to be created.
        y - The y-axis value of the actor to be created.

      • nodeBinary

        public static java.lang.String nodeBinary()
                                   throws java.io.IOException
        Return the node binary that is in the path or, if node is not found in the path, return the node binary in $PTII/vendors/node.
        Returns:
        The node binary or "node".
        Throws:
        java.io.IOException - If there is a problem finding the node binary.

      • npmBinary

        public static java.lang.String npmBinary()
                                  throws java.io.IOException
        Return the npm binary that is in the path or, if npm is not found in the path, return the npm binary in $PTII/vendors/node.
        Returns:
        The npm binary or "npm".
        Throws:
        java.io.IOException - If there is a problem finding the npm binary.

      • reload

        public void reload()
            throws IllegalActionException,
                   java.io.IOException,
                   javax.xml.transform.TransformerConfigurationException
        Reload an accessor. The repository containing the accessors is checked out or updated and JSDoc is run on the documentation.
        Throws:
        IllegalActionException - If no source file is specified.
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.

      • reload

        public void reload​(boolean obeyCheckoutOrUpdateRepositoryParameter)
            throws IllegalActionException,
                   java.io.IOException,
                   javax.xml.transform.TransformerConfigurationException
        Reload an accessor.
        Parameters:
        obeyCheckoutOrUpdateRepositoryParameter - If true, then use the value of the checkoutOrUpdateRepository parameter. If false, then override the value of the checkoutOrUpdateRepository parameter and do not checkout or update the repository or invoke JSDoc. During testing, this parameter is set to false after the first reload of an accessor so as to improve the performance of the tests.
        Throws:
        IllegalActionException - If no source file is specified.
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.

      • reloadAllAccessors

        public static boolean reloadAllAccessors​(CompositeEntity composite)
                                  throws IllegalActionException,
                                         java.io.IOException,
                                         javax.xml.transform.TransformerConfigurationException
        Reload all the JSAccessors in a CompositeEntity. The first time this method is invoked, the accessors repository will be checked out or updated and JSDoc invoked. The second and subsequent times the method is invoked, the checkout or update and JSDoc invocation will not occur. This is done so as to make testing faster. If the script of a JSAccessor has local modifications, then the user is asked if they want to override them.
        Parameters:
        composite - The composite that contains the JSAccessors
        Returns:
        true if the model contained any JSAccessors.
        Throws:
        IllegalActionException - If no source file is specified.
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.

      • reloadAllAccessors

        public static boolean reloadAllAccessors​(CompositeEntity composite,
                                         boolean promptForOverrideOfLocalModifications)
                                  throws IllegalActionException,
                                         java.io.IOException,
                                         javax.xml.transform.TransformerConfigurationException
        Reload all the JSAccessors in a CompositeEntity. The first time this method is invoked, the accessors repository will be checked out or updated and JSDoc invoked. The second and subsequent times the method is invoked, the checkout or update and JSDoc invocation will not occur. This is done so as to make testing faster.
        Parameters:
        composite - The composite that contains the JSAccessors
        promptForOverrideOfLocalModifications - If true, then prompt the user and ask if they want to override local modifications If false, then accessors with local modifications are not reloaded.
        Returns:
        true if the model contained any JSAccessors.
        Throws:
        IllegalActionException - If no source file is specified.
        java.io.IOException - If the urlSpec cannot be converted, opened read, parsed or closed.
        javax.xml.transform.TransformerConfigurationException - If a factory cannot be created from the xslt file.

      • _accessorClass

        protected java.lang.String _accessorClass()
        Return the name of the accessor class. In this base class, it returns the value of the accessorSource parameter. If the accessorSource parameter does not yet exist, then this returns "Unknown".
        Overrides:
        _accessorClass in class JavaScript
        Returns:
        The value of the accessorSource parameter.

      • _sourceToURL

        protected static java.net.URL _sourceToURL​(java.lang.String urlSpec,
                                           boolean updateRepository)
                                    throws IllegalActionException,
                                           java.io.IOException,
                                           java.net.MalformedURLException
        For the given URL specification, attempt to find a local copy of the resource and return that if it exists. Otherwise, return the URL specified. If updateRepository is true, or if an exception occurs accessing the local copy, then attempt to update the accessor repository on the local file system. Do this only once in this instance of the JVM, as it is quite costly, unless the last update was more than 12 hours ago.
        Parameters:
        urlSpec - The URL specification.
        updateRepository - True to update the repository before attempting to find the local file.
        Returns:
        The local version of the URL, or the URL given by the specification if the local version cannot be found.
        Throws:
        IllegalActionException - If no urlSpec is given.
        java.io.IOException - If the URL cannot be found.
        java.net.MalformedURLException - If the URL specification is malformed.

      • getAccessorNetworkAccessAllowed

        public static boolean getAccessorNetworkAccessAllowed()
        Return true if the PT_NO_NET environment variable is set.