I've updated my draft internet draft of a proxylet API to incorporate all the
suggestions made on this list. The majority of the changes relate to the
event package which allow the proxylet to be asynchronously passed external
events.
The full version of the draft can be found here: -
http://www.thundercrack.com/drafts/draft-walker-opes-proxylet-java-binding-01.txt
Change log (http://www.thundercrack.com/drafts/changelog-orig-01.txt)
Changes from previous draft ID.
1. External events are notifiable via an event API.
2. Proxylet allowed to write a response in processing points 1 + 2
3. Protocol Version methods made consistent.
4. Accessors and mutators added for http response status code and
message.
Details: - (note this isnt a full diff )
< If the proxylet is carrying out a modRequest service, the proxylet
< may be able formulate the response in its entirity. The proxylet
< author may directly respond to the request via an output stream
< accessed by a call to getResponseOutputStream (Section 7.7.17).
<
< Events which are related to the execution of the proxylet, but are
< external to the proxylet are reported via an event framework (Section
< 5). Events such as service timeout, client disconnection, server
< disconnection, and system shutdown may be dispatched to the listeners
< registered to receive them. This dispatching occurs in a thread
< seperate from the proxylet's service thread allowing the proxylet to
< asynchronously receive signals.
---
< The proxylet's execution may be affected by external events. For
< example, a proxylet may wish to stop its service when the user agent
< connection is terminated prematurely mid processing. The proxylet
< will be informed of this change in circumstances by receiving a
< DisconnectionEvent (Section 7.18). This event will be dispatched to
< the proxylet's registered ProxyletEventListener. The
< DisconnectionEvent is passed asynchronously via a seperate thread to
< the proxylet's listener allowing the listener to change the
< proxylet's course of action as appropriate.
---
< Two interfaces are included in the event model for two distinct types
< of external event.
<
< o Interface ProxyEventListener (Section 7.14) receives events
< related to the proxylet engine
<
< o Interface ProxyletEventListener (Section 7.17) receives events
< related to a particular proxylet instance which is actively in
< service
<
< Global events like the server shutdown should be dispatched via the
< ProxyEventListener. ProxyEventListeners will be registered with the
< ProxyletContext.
<
< Events relating to a single service thread passing through a proxylet
< should be dispatched via the ProxyletEventListener.
< ProxyletEventListeners should be registered with the ProxyletRequest.
<
< 5. Overview of Package: org.ietf.opes.proxylet.event
<
< ProxyletEventListener
<
< The Listener interface for ProxyEvents relating to the individual
< Proxylet, for instance if the user agent associated with a request
< disconnects from the OPES device mid proxylet execution.
<
< ProxyEventListener
<
< The Listener interface for ProxyEvents, ProxyEventListener, allows
< a ProxyEvent to be received by the listening object.
<
< ProxyEvent
<
< Base class for the events that may be sent to a ProxyEventListener
< or a ProxyletEventListener.
<
< ProxyShutdownEvent
<
< ProxyShutdownEvent extends ProxyEvent and is an PROXY_LOCAL event
< indicating that a proxylet engine is shutting down.
<
< ServiceTimeoutEvent
<
< ServiceTimeoutEvent extends ProxyEvent and is an PROXY_LOCAL event
< indicating that a proxylet service seems to have been idle
< processing for too long.
<
< DisconnectionEvent
<
< Whenever one of the parties involved with the data transport
< closes its connection prematurely, a DisconnectionEvent will be
< received by the org.ietf.opes.proxylet.event.ProxyletEventListener
< (Section 7.17).
<
< ProxyEventSource
<
< ProxyEventSource allows the ProxyEvent objects to indicate the
< source of the event.
<
<
<
< 7.5.9 Method ProxyletContext.registerProxyEventListener
<
< Signature: public void registerProxyEventListener( ProxyEventListener
< listener )
<
< Parameters:
<
< 1. ProxyEventListener listener. The ProxyEventListener that will
< process any events that are sent by the Proxylet Engine.
<
< Returns: void.
<
< Description:
<
< Register a ProxyEventListener with the underlying Proxylet Engine
< allowing the listener to react to a set of possible events that could
< occur at the proxylet engine.
<
<
< 7.5.10 Method ProxyletContext.deregisterProxyEventListener
<
< Signature: public void deregisterProxyEventListener(
< ProxyEventListener listener )
<
< Parameters:
<
< 1. ProxyEventListener listener. The ProxyEventListener that was
< waiting to process any events that are sent by the Proxylet
< Engine.
<
< Returns: void.
<
< Description:
<
< Remove the passed listener from the list of objects waiting to react
< to events sent from the Proxylet Engine.
<
<
---
<
7.7.2 Method ProxyletRequest.getProtocol
< Returns: String. A String containing the protocol name and version
< number
---
Returns: String. A String containing the protocol name.
---
< Returns the name and version of the protocol the response uses. This
< takes the form protocol/majorVersion.minorVersion. For example
< HTTP/1.1.
---
Returns the name of the protocol the request uses. for example HTTP.
< Returns the version details of the protocol the request uses. For
< example if the protocol was HTTP/1.1 the method would return 1.1 as a
< String.
1614,1617d1508
< Description:
<
< Get the host for which this request is intended.
<
1862,1927c1757
< 7.7.15 Method ProxyletRequest.registerProxyletEventListener
<
< Signature: public void registerProxyletEventListener(
< ProxyletEventListener listener )
<
< Parameters:
<
< 1. ProxyletEventListener listener. The ProxyletEventListener that
< will process any events that are sent by the Proxylet Engine.
<
< Returns: void.
<
< Description:
<
< Register a ProxylteEventListener with the underlying Proxylet Engine
< allowing the listener to react to a set of possible events that could
< occur at the proxylet engine that are associated with this particular
< request.
<
<
< 7.7.16 Method ProxyletRequest.deregisterProxyEventListener
<
< Signature: public void deregisterProxyEventListener(
< ProxyletEventListener listener )
<
< Parameters:
<
< 1. ProxyletEventListener listener. The ProxyEventListener that was
< waiting to process any events that are sent by the Proxylet
< Engine.
<
< Returns: void.
<
< Description:
<
< Remove the passed listener from the list of objects waiting to react
< to events sent from the Proxylet Engine.
<
<
<
<
ProxyletRequest allowed to generate a response
===================================
<
<
< 7.7.17 Method ProxyletRequest.getResponseOutputStream
<
< Signature: public OutputStream getResponseOutputStream()
<
< Parameters: None.
<
< Returns: OutputStream. OutputStream The output stream which allows
< the proxylet author to compose a fresh response.
<
< Description:
<
< Forms an output stream allowing the proxylet author to respond to the
< request without passing the request on to an origin server. This
< output stream will be sent directly to the user agent. This method
< should only be used in processing positions 1 and 2. The use of this
< method in other processing points will result in the returning of
< null.
<
<
Protocol Version Differences
=====================
< 7.8.3 Method ProxyletResponse.getProtocolVersion
<
< Signature: public String getProtocolVersion()
<
< Parameters: None.
<
< Returns: String. A String containing the protocol version number.
<
< Description:
<
< Returns the version details of the protocol the response uses. For
< example if the protocol was HTTP/1.1 the method would return 1.1 as a
< String.
<
<
2059,2065c1879,1880
< Method ProxyletResponse.getRemoteAddr
< Returns the IP address of the server that sent the response. This is
< the IP address from which this response was received by the OPES
< device. This could be either the origin server, or the nearest
< upstream device acting in the capacity as the origin server.
<
---
Returns the IP address of the server that sent the request. This is
the IP address from which the response has been sent.
Proxylet Event Package Details
=======================
< 7.13 ProxyEvent
<
< Base class for the events that may be sent to a ProxyEventListener or
< a ProxyletEventListener. A ProxyEvent will be received by the
< org.ietf.opes.proxylet.event.ProxyEventListener (Section 7.14) in a
< seperate thread to that which it is carrying out its service. This
< allows asynchronous events to be dispatched to the Proxylet services.
< Examples of ProxyEvents are: -
<
< o DisconnectionEvent. Whenever the client disconnects, or the
< origin server disconnects itself from the proxy, suitable tidy up
< may be required by the Proxylet. An option for the proxylet
< author may be to continue processing the request on a client
< disconnection so that subsequent requests may be responded to with
< cached results, alternatively any data that is currently partially
< processed may be discarded and resources cleared up. At the edges
< of the proxylet chain, disconnection will may also be determined
< by IOStreamException being thrown on the payload input and output
< streams.
<
< o ProxyShutdownEvent. If the proxy is begining to shutdown, the
< proxylet author may wish to do some tidying up of resources.
<
< o ServiceTimeoutEvent. If the proxylet service is taking longer
< than anticipated the OPES device will indicate that its been
< taking too long by passing it a ServiceTimeoutEvent.
<
<
< 7.13.1 Method ProxyEvent.getRequest
<
< Signature: public ProxyletRequest getRequest()
<
< Parameters: None.
<
< Returns: ProxyletRequest. The ProxyletRequest with which the event
< is associated or null if none is appropriate.
<
< Description:
<
< Accessor for the request with which this event is associated. If no
< request is directly associated with the event, null is returned.
<
<
< 7.13.2 Method ProxyEvent.getResponse
<
< Signature: public ProxyletResponse getResponse()
<
< Parameters: None.
<
<
<
< Walker Expires January 30, 2002 [Page 50]
<
<
< Returns: ProxyletResponse. The ProxyletResponse with which the event
< is associated or null if none is appropriate.
<
< Description:
<
< Accessor for the response with which this event is associated. If no
< response is directly associated with the event, null is returned.
<
<
< 7.14 ProxyEventListener
<
< ProxyEventListener extends interface java.util.EventListener
< inheriting all methods.
<
< The Listener interface for ProxyEvents, ProxyEventListener, allows a
< ProxyEvent to be received by the listening object. This interface
< allows arbitrary events to be asynchronously presented to the
< Proxylet. Proxylets are not automatically registered as
< ProxyEventListeners with the underlying Proxylet Engine. The
< Proxylet author must implement the ProxyEventListener interface and
< register their listener with the ProxyletContext. The Proxylet
< should not be placed into a position where it needs to react to an
< asynchronous event before it has its ProxyEventListener registered.
<
< 7.14.1 Method ProxyEventListener.proxyEvent
<
< Signature: public void proxyEvent( ProxyEvent event )
<
< Parameters:
<
< 1. ProxyEvent event. The ProxyEvent that the proxylet may react to.
<
< Returns: void.
<
< Description:
<
< General all purpose proxy event method. The method will be called
< whenever any proxy event occurs.
<
<
< 7.14.2 Method ProxyEventListener.proxyShuttingDown
<
< Signature: public void proxyShuttingDown( ProxyShutdownEvent event )
<
< Parameters:
<
< 1. ProxyShutdownEvent event. The ProxyEvent that the proxylet may
< react to.
<
< Returns: void.
<
<
<
< Walker Expires January 30, 2002 [Page 51]
<
< Internet-Draft Proxylet Java API August 2001
<
<
< Description:
<
< Called whenever the Proxylet Engine is shutting down.
<
<
< 7.15 ProxyShutdownEvent
<
< ProxyShutdownEvent extends ProxyEvent and is an PROXY_LOCAL event
< indicating that a proxylet engine is shutting down. The Proxylet
< author may listen for these events by registering a
< ProxyEventListener with the ProxyletRequest object.
< If no requests are currently being processed by a Proxylet, the
< ProxyShutdownEvent will be unobserved by the Proxylet, no special mid
< processing tidy-up routines will be required, and the Proxylet will
< simple react to the engine shutdown by having its destroy method
< called.
<
< 7.16 ProxyEventSource
<
< ProxyEventSource allows the ProxyEvent objects to indicate the source
< of the event. For example when the user agent disconnects
< prematurely the server will generate a DisconnectionEvent with
< DOWNSTREAM_CLIENT as its source.
<
< 7.16.1 Available Fields
<
< o UPSTREAM_SERVER.
<
< Field that indicates the event comes as a result of action by the
< upstream server
<
< o DOWNSTREAM_CLIENT.
<
< Field that indicates the event comes as a result of action by the
< downstream client. This could either be the user agent, or the
< next server in the chain.
<
< o LOCAL_SERVER.
<
< Field that indicates the source of the event comes as a result of
< action by the local server.
<
<
< 7.16.2 Method ProxyEventSource.getSource
<
< Signature: public String getSource()
<
< Parameters: None.
<
<
<
< Walker Expires January 30, 2002 [Page 52]
<
<
< Returns: String.
<
< Description:
<
< Returns the a text representation of the source of the event options
< are: -
<
< o UPSTREAM_SERVER
<
< o DOWNSTREAM_CLIENT
<
< o PROXY
<
<
<
< 7.16.3 Method ProxyEventSource.equals
<
< Signature: public boolean equals( Object o )
<
< Parameters:
<
< 1. Object o.
<
< Returns: boolean.
<
< Description:
<
<
<
< 7.17 ProxyletEventListener
<
< The Listener interface for ProxyEvents relating to the individual
< Proxylet, for instance if the user agent associated with a request
< disconnects from the OPES device mid proxylet execution. Proxylet
< authors must implement this interface in order to react to any
< DisconnectionEvent, ServiceTimeoutEvent, and any other yet to be
< defined ProxyEvents associated with the particular Proxylet. The
< Listener must be registered with the ProxyletRequest to enable the
< event to be transported to the listener. Events a presented where
< possible to the appropriate receiving method.
<
< o DisconnectionEvent is passed to the clientDisconnected and
< serverDisconnected methods in the event that the other parties
< involved in the message dispatching terminate their communication
< connections.
<
< o ServiceTimeoutEvent is passed to the serviceTimeout method if the
< Proxylet Engine determines that the service has been processing
< for too long.
<
<
<
<
< Walker Expires January 30, 2002 [Page 53]
<
< Internet-Draft Proxylet Java API August 2001
<
<
< o Events that are added by the Proxylet Engine author are sent to
< the general proxyEvent method.
<
< The Proxylet author should register any ProxyletEventListener before
< placing the Proxylet service in a state whereby it would need to
< react to any asynchronous event enabling
<
< 7.17.1 Method ProxyletEventListener.clientDisconnected
<
< Signature: public void clientDisconnected( DisconnectionEvent
< discEvent )
<
< Parameters:
<
< 1. DisconnectionEvent discEvent. The DisconnectionEvent indicating
< that the client has disconnected.
<
< Returns: void.
<
< Description:
<
< Called whenever the entity forming the request to the opes device
< disconnects from the device. The disconnection event should have
< ProxyEventSource.DOWNSTREAM_CLIENT as its object source.
<
<
< 7.17.2 Method ProxyletEventListener.serverDisconnected
<
< Signature: public void serverDisconnected( DisconnectionEvent
< discEvent )
<
< Parameters:
<
< 1. DisconnectionEvent discEvent. The DisconnectionEvent indicating
< that the client has disconnected.
<
< Returns: void.
<
< Description:
<
< Called whenever the entity producing the upstream response
< disconnects from the device prematurely. The event should hold
< ProxyEventSource.UPSTREAM_SERVER as its object source.
<
<
<
<
<
<
<
<
< Walker Expires January 30, 2002 [Page 54]
<
< Internet-Draft Proxylet Java API August 2001
<
<
< 7.17.3 Method ProxyletEventListener.serviceTimeout
<
< Signature: public void serviceTimeout( ServiceTimeoutEvent event )
< throws ProxyletException
<
< Parameters:
<
< 1. ServiceTimeoutEvent event. The ServiceTimeoutEvent that the
< proxylet may react to.
<
< Returns: void.
<
< Throws:
<
< o org.ietf.opes.proxylet.ProxyletException.
< Thrown whenever difficulties arise within the Proxylet during the
< reaction to the timeout event.
<
< Description:
<
< Called whenever the proxylet service seems to be taking too long.
<
<
< 7.17.4 Method ProxyletEventListener.proxyEvent
<
< Signature: public void proxyEvent( ProxyEvent event ) throws
< ProxyletException
<
< Parameters:
<
< 1. ProxyEvent event. The ProxyEvent that the proxylet may react to.
< Returns: void.
<
< Throws:
< o org.ietf.opes.proxylet.ProxyletException.
< Thrown whenever difficulties arise within the Proxylet during the
< reaction to the proxy event.
< General all purpose proxy event method. The method will be called
< whenever any proxy event occurs.
< 7.18 DisconnectionEvent
< Whenever one of the parties involved with the data transport closes
< its connection prematurely, a DisconnectionEvent will be received by
< the org.ietf.opes.proxylet.event.ProxyletEventListener (Section
< 7.17).
< If the upstream server terminates its connection prior to the end of
< the current message, a DisconnectionEvent will be generated and
< passed to each of the registered ProxyletEventListeners. If the
< upstream server has completed its message, no event will be sent.
< 7.19 ServiceTimeoutEvent
< ServiceTimeoutEvent extends ProxyEvent and is an PROXY_LOCAL event
< indicating that a proxylet service seems to have been idle processing
< for too long. The proxylet author may listen for these events by
< registering a ProxyEventListener with the ProxyletRequest object.
< A Proxylet author should signal the service code that the engine has
< detected an time overrun. If the Proxylet may be waiting for some
< signal, the thread may be interupted by the author. If the
< ServiceTimeoutEvent fails to free up the Proxylet service and
< terminate its service, the Proxylet Engine will be allowed to
< forcibly terminate the service.
Protocol Version Differences
=====================
< Signature: public String getVersion()
< Returns: String. An String holding the version of the cookie
< mechanism.
---
Returns: int. An int holding the version of the cookie mechanism/.
< 7.20.12 Method HTTPCookie.setVersion
< Signature: public void setVersion( String version )
< 1. String version. An String holding the version of the cookie
< mechanism to be used.
---
Signature: public void setVersion( int version )
1. int version. An int holding the version of the cookie mechanism
to be used.
HTTP Response Status code differences
==============================
< 7.23.17 Method HTTPProxyletResponse.getStatusCode
<
< Signature: public int getStatusCode()
<
< Parameters: None.
<
< Returns: int. An int holding the value of the status code contained
< within the response.
<
< Description:
<
< Return the status code associated with the response message.
<
<
< 7.23.18 Method HTTPProxyletResponse.setStatusCode
<
< Signature: public void setStatusCode( int code )
<
< Parameters:
<
< 1. int code. The value to insert as the status code.
<
< Returns: void.
<
< Description:
< Sets the status code in the HTTP response.
<
< 7.23.19 Method HTTPProxyletResponse.getStatusMessage
<
< Signature: public String getStatusMessage()
<
< Parameters: None.
<
< Returns: String. An String holding the status message.
<
< Description:
<
< Returns the message associated with the responses status code.
< Examples of the codes and messages can be found in the HTTP RFC's.
<
< 7.23.20 Method HTTPProxyletResponse.setStatusMessage
<
< Signature: public void setStatusMessage( String message )
<
< Parameters:
<
< 1. String message. The value to insert as the status code.
<
< Returns: void.
<
< Description:
< Sets the status message in the HTTP response.
--
Regards,
Andrew Walker
Thundercrack Ltd.
17 Rathbone Street
London, W1T 1ND
UK
Phone: +44 020 7631 1000
EMail: andrew(_dot_)walker(_at_)thundercrack(_dot_)com
URI: http://www.thundercrack.com