org.ptolemy.ptango.lib

Class HttpActor

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity<T>

ptolemy.actor.AtomicActor<TypedIOPort>

ptolemy.actor.TypedAtomicActor

org.ptolemy.ptango.lib.HttpActor

All Implemented Interfaces:

java.lang.Cloneable, HttpService, Actor, Executable, FiringsRecordable, Initializable, ExceptionSubscriber, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class HttpActor
extends TypedAtomicActor
implements HttpService, ExceptionSubscriber

An actor that handles an HTTP request by producing output and waiting for an input that provides a response. This actor requires that the model that contains it includes an instance of WebServer, which discovers this actor and delegates HTTP requests to a servlet that this actor creates. It also requires that the model containing this actor provide exactly one input to either the response or setCookies input port (or both) in response to every output request, and that such responses are delivered in the same order as the requests they are responding to.

The path parameter specifies which HTTP requests will be delegated to this actor. If the base URL for the web server is "http://localhost:8080", say, then request of the form "http://localhost:8080/path" will be delegated to this actor.

When this actor receives an HTTP request from the WebServer, it issues a request for the director to fire it at the greater of the current time of the director or the time elapsed since the last invocation of initialize() (in seconds). When the actor fires, it produces on its output ports the details of the request, time stamped by the elapsed time since the model started executing. It expects to be in a model that will send it data to either the response or setCookies input port (or both) with the response to HTTP request. If that response does not arrive within timeout (default 30000) milliseconds, then this actor will a issue timeout response and will discard the response when it eventually arrives.

This actor is designed to be used in a DE model (with a DEDirector). Since a model using this actor must deliver a response for every request, the model must put this actor in a feedback loop. The requests appear on the outputs of this actor, and the responses appear on the inputs. Each such feedback loop is required to include an instance of MicrostepDelay (or TimeDelay, if you wish to model response times) in order to break the causality loop that the feedback loop would otherwise incur. The downstream model should be used to construct a response. For example, to simply serve a web page, put a FileReader actor to read the response from a local file and a MicrostepDelay downstream in a feedback loop connected back to the response input.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Elizabeth Latronico and Edward A. Lee

See Also:

WebServer

Pt.AcceptedRating:

Red (ltrnc)

Pt.ProposedRating:

Red (ltrnc)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	HttpActor.ActorServlet A servlet providing implementations of get and post.
protected static class	HttpActor.HttpRequestItems A data structure with all the relevant information about an HTTP request.
protected static class	HttpActor.HttpResponseItems A data structure with all the relevant information about an HTTP response.

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
TypedIOPort	getCookies An output that sends the cookies specified by the requestedCookies parameter, with values provided by a get request.
TypedIOPort	getParameters An output port that sends parameters included in a get request.
TypedIOPort	getRequestURI An output port that sends the relative URI of a get request, which must match the pattern given by the path parameter.
StringParameter	path The relative URL of HTTP requests that this actor handles.
TypedIOPort	postBody An output that sends the body of the request, if any.
TypedIOPort	postCookies An output that sends the cookies specified by the requestedCookies parameter, with values provided by a post request.
TypedIOPort	postParameters An output port that sends parameters included in a post request.
TypedIOPort	postRequestURI An output port that sends the relative URI of a post request, which must match the pattern given by the path parameter.
TypedIOPort	putBody An output that sends the body of the request, if any.
TypedIOPort	putCookies An output that sends the cookies specified by the requestedCookies parameter, with values provided by a put request.
TypedIOPort	putParameters An output port that sends parameters included in a put request.
TypedIOPort	putRequestURI An output port that sends the relative URI of a put request, which must match the pattern given by the path parameter.
Parameter	requestedCookies An array of names of cookies that this actor should retrieve from an HTTP request and produce on the getCookies and putCookies output ports.
TypedIOPort	response An input port on which to provide the response to issue to an HTTP request.
TypedIOPort	setCookies An input on which to provide new cookies and/or new cookie values.
Parameter	timeout The time in milliseconds to wait after producing the details of a request on the output ports for a response to appear at the input ports.

Fields inherited from class ptolemy.actor.TypedAtomicActor

_typesValid

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Constructors

Constructor and Description
HttpActor(CompositeEntity container, java.lang.String name) Create an instance of the actor.

Method Summary

Modifier and Type	Method and Description
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the actor.
boolean	exceptionHandled(boolean succesful, java.lang.String message) Not used here.
boolean	exceptionOccurred(java.lang.String policy, java.lang.Throwable exception) Generate an HTTP response for the client if an exception occurs.
void	fire() If there are input tokens on the response or setCookies ports, then queue a response to be sent by the servelet for a corresponding request.
java.net.URI	getRelativePath() Return the relative path that this HttpService is mapped to, which is the value of the path parameter.
javax.servlet.http.HttpServlet	getServlet() Create and return an HttpServlet that is used to handle requests that arrive at the path given by the path parameter.
void	initialize() Record the current model time and the current real time so that output events can be time stamped with the elapsed time since model start.
void	setRelativePath(java.net.URI path) Set the relative path that this HttpService is mapped to.
void	setWebServer(WebServer server) Specify the web server for this service.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_containedTypeConstraints, _customTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_addPort, _description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

getCookies

public TypedIOPort getCookies

An output that sends the cookies specified by the requestedCookies parameter, with values provided by a get request. If the get request does have cookies with names matching those in requestedCookies, then those values will be empty strings. The output will be a RecordToken with the field names given by requestedCookies, and the field values being strings.

getParameters

public TypedIOPort getParameters

An output port that sends parameters included in a get request. These are values appended to the URL in the form of ...?name=value. The output will be a record with one field for each name. If the request assigns multiple values to the same name, then the field value of the record will be an array of strings. Otherwise, it will simply be a string.

getRequestURI

public TypedIOPort getRequestURI

An output port that sends the relative URI of a get request, which must match the pattern given by the path parameter. This has type string.

path

public StringParameter path

The relative URL of HTTP requests that this actor handles. This is a string that defaults to "/*", meaning that all requests are handled, unless there is another instance of the actor with a more specific path that matches. Preference is given to longer paths. So, for example, a request "http://localhost:8080/foo/bar" will be delegated to an actor with path = "/foo/bar/*", if there is one, and otherwise to an actor with path = "/foo/*", if there is one, and finally to an actor with path = "/*", if the first two don't exist. If two actors specify the same path, then it is undefined which one gets the request.

postBody

public TypedIOPort postBody

An output that sends the body of the request, if any. HTTPActor only offers a body output for POST and PUT requests. While it is technically possible for a GET request to have a body, this is discouraged since GET requests are supposed to be idempotent.

postCookies

public TypedIOPort postCookies

An output that sends the cookies specified by the requestedCookies parameter, with values provided by a post request. If the post request does have cookies with names matching those in requestedCookies, then those values will be empty strings. The output will be a RecordToken with the field names given by requestedCookies, and the field values being strings.

postParameters

public TypedIOPort postParameters

An output port that sends parameters included in a post request. The output will be a record with one field for each name. If the request assigns multiple values to the name, then the field value of the record will be an array of strings. Otherwise, it will simply be a string.

postRequestURI

public TypedIOPort postRequestURI

An output port that sends the relative URI of a post request, which must match the pattern given by the path parameter. This has type string.

putBody

public TypedIOPort putBody

An output that sends the body of the request, if any. HTTPActor only offers a body output for POST and PUT requests. While it is technically possible for a GET request to have a body, this is discouraged since GET requests are supposed to be idempotent.

putCookies

public TypedIOPort putCookies

An output that sends the cookies specified by the requestedCookies parameter, with values provided by a put request. If the put request does have cookies with names matching those in requestedCookies, then those values will be empty strings. The output will be a RecordToken with the field names given by requestedCookies, and the field values being strings.

putParameters

public TypedIOPort putParameters

An output port that sends parameters included in a put request. The output will be a record with one field for each name. If the request assigns multiple values to the name, then the field value of the record will be an array of strings. Otherwise, it will simply be a string.

putRequestURI

public TypedIOPort putRequestURI

An output port that sends the relative URI of a put request, which must match the pattern given by the path parameter. This has type string.

requestedCookies

public Parameter requestedCookies

An array of names of cookies that this actor should retrieve from an HTTP request and produce on the getCookies and putCookies output ports. This is an array of strings that defaults to an empty array.

response

public TypedIOPort response

An input port on which to provide the response to issue to an HTTP request. When this input port receives an event, if there is a pending get or post request from a web server, then that pending request responds with the value of the input. Otherwise, the response is recorded, and the next get or post request received will be given the response. For convenience, this is a multiport, and a response can be provided on any input channel. If multiple responses are provided simultaneously, the last one (on the highest numbered channel) will prevail.

setCookies

public TypedIOPort setCookies

An input on which to provide new cookies and/or new cookie values. These will be set in the HttpResponse received on the response input in the same firing, or if there is no token on the response input, will be treated as cookies accompanying an empty string response. This has type record.

timeout

public Parameter timeout

The time in milliseconds to wait after producing the details of a request on the output ports for a response to appear at the input ports. This is a long that defaults to 30,000. If this time expires before an input is received, then this actor will issue a generic timeout response to the HTTP request.

Constructor Detail

HttpActor

public HttpActor(CompositeEntity container,
                 java.lang.String name)
          throws IllegalActionException,
                 NameDuplicationException

Create an instance of the actor.

Parameters:

container - The container

name - The name.

Throws:

IllegalActionException - If the superclass throws it.

NameDuplicationException - If the super

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. In this case, check the value of the path attribute to make sure it is a valid URI.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor.

Overrides:

clone in class TypedAtomicActor

Parameters:

workspace - The workspace in which to place the cloned attribute.

Returns:

The cloned attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class.

See Also:

Object.clone()

exceptionHandled

public boolean exceptionHandled(boolean succesful,
                                java.lang.String message)

Not used here. Required for ExceptionSubscriber interface.

Specified by:

exceptionHandled in interface ExceptionSubscriber

Parameters:

succesful - True if the exception was successfully handled; false otherwise

message - A status message from the exception handler

Returns:

True if the subscriber successfully processed the information; false otherwise (for example, an ExceptionEmailer that fails to send an email)

exceptionOccurred

public boolean exceptionOccurred(java.lang.String policy,
                                 java.lang.Throwable exception)

Generate an HTTP response for the client if an exception occurs. No response will be received on the input port in the event of an exception.

Specified by:

exceptionOccurred in interface ExceptionSubscriber

Parameters:

policy - The exception handling policy of the exception handler; see CatchExceptionAttribute

exception - The exception that occurred

Returns:

True since a response is always sent to the client, and there there are no operations that throw exceptions

getRelativePath

public java.net.URI getRelativePath()

Return the relative path that this HttpService is mapped to, which is the value of the path parameter. This method is required by the HttpService interface.

Specified by:

getRelativePath in interface HttpService

Returns:

The relative path that this HttpService is mapped to.

See Also:

setRelativePath(URI)

getServlet

public javax.servlet.http.HttpServlet getServlet()

Create and return an HttpServlet that is used to handle requests that arrive at the path given by the path parameter. This method is required by the HttpService interface.

Specified by:

getServlet in interface HttpService

Returns:

An HttpServlet to handle requests.

fire

public void fire()
          throws IllegalActionException

If there are input tokens on the response or setCookies ports, then queue a response to be sent by the servelet for a corresponding request. If the servlet has received an HTTP request, then also produce on the output ports the details of the request. If there is an HTTP request, but the current superdense time matches the time of the previously produced output, then request a refiring at the current time (next microstep) so that the outputs are produced at the next microstep. This actor is designed to normally be fired twice at each superdense time, first to produce outputs corresponding to an HTTP request, and next to send back the response to that request. This strategy avoids creating signals with multiple values at the same superdense time instant.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If sending the outputs fails.

initialize

public void initialize()
                throws IllegalActionException

Record the current model time and the current real time so that output events can be time stamped with the elapsed time since model start.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If the superclass throws it.

setRelativePath

public void setRelativePath(java.net.URI path)

Set the relative path that this HttpService is mapped to. This method is required by the HttpService interface.

Specified by:

setRelativePath in interface HttpService

Parameters:

path - The relative path that this HttpService is mapped to.

See Also:

getRelativePath()

setWebServer

public void setWebServer(WebServer server)

Specify the web server for this service. This will be called by the WebServer attribute of a model, if there is one, and will enable this service to access information about the web server (such as the resourcePath, resourceLocation, or temporaryFileLocation).

Specified by:

setWebServer in interface HttpService

Parameters:

server - The WebServer for this service