com.virtualweaver.xotics.dialect.xape.engine
Class XapEngine

java.lang.Object
  extended bycom.virtualweaver.xotics.dialect.xape.engine.XapEngine

public final class XapEngine
extends java.lang.Object

This class is the XAP engine. though it can be used directly to be integrated in any development, XapPlayer should be preferred, as it adds XML config support. Notice that any method of this can be called at any time.

Version:
2.1
See Also:
XapPlayer

Constructor Summary
XapEngine(com.virtualweaver.xotics.datamodel.XoEnvironment env)
          The engine is instanciated with an existing XO environment.
 
Method Summary
 void addShareSpace(java.lang.String spaceName)
          Adds a share space.
static XapRequest createRequest(com.virtualweaver.xotics.datamodel.XoEnvironment env, byte type, java.lang.String appName, java.lang.String instanceName, java.lang.String handler, java.lang.String reqId, XapQueue responseQueue, com.virtualweaver.xotics.datamodel.XoObject contentObject)
          This is a utility method to create a request object, root of an XML subtree dedicated to be integrated into the private context of an app instance.
static XapRequest createShutdownMessage(com.virtualweaver.xotics.datamodel.XoEnvironment env, java.lang.String appName, java.lang.String instanceName)
          Utility method to create a special message requesting the shutdown of a particular App instance.
static XapRequest createStartupMessage(com.virtualweaver.xotics.datamodel.XoEnvironment env, java.lang.String appName, java.lang.String instanceName)
          Creates a special message requesting the launch of a new Instance, named instanceName, from a loaded Application identified by appName.
 com.virtualweaver.xotics.datamodel.XoEnvironment getEnvironment()
          Accessor to current XO environment.
 XapRepository getRepository()
          Returns the repository, an object able to provide name of current applications, instances and share spaces.
 void loadApplication(com.virtualweaver.xotics.datamodel.XoDMInstance appDoc, java.lang.String name, java.util.Map parameters)
          Loads an application, composed with an app document (XAPE APP dialect) and associated config parameters.
 XapResponse sendRequest(XapRequest req)
          Sends a request.
 void setParameter(java.lang.String param, java.lang.Object value)
          Sets a config parameter.
 void shutdown()
          Stops the engine.
 void startup()
          Starts the engine.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XapEngine

public XapEngine(com.virtualweaver.xotics.datamodel.XoEnvironment env)
          throws XapException
The engine is instanciated with an existing XO environment. XAPE dialect implementations are loaded if missing.

Parameters:
env - an existing XO environment
Throws:
XapException - if some error occurs during dialect implementation loading process
Method Detail

getEnvironment

public com.virtualweaver.xotics.datamodel.XoEnvironment getEnvironment()
Accessor to current XO environment.

Returns:
XO environment used to instanciate this

startup

public void startup()
             throws XapException
Starts the engine. If this is already started, this method returns silently.

Throws:
XapException - if some error occurs during startup process

getRepository

public XapRepository getRepository()
Returns the repository, an object able to provide name of current applications, instances and share spaces.

Returns:
the repository

shutdown

public void shutdown()
Stops the engine. Running instances continue, but no more instance can be instanciated, and each running instance receives a shutdown system message which make them to jump to either or state.


setParameter

public void setParameter(java.lang.String param,
                         java.lang.Object value)
                  throws XapException
Sets a config parameter. Valid param names are : from XapConstants

Parameters:
param - the name of the param
value - corresponding value
Throws:
XapException - if invalid param name or value is provided
See Also:
XapConstants

addShareSpace

public void addShareSpace(java.lang.String spaceName)
                   throws XapException
Adds a share space. If the space exists already, this method does nothing.

Parameters:
spaceName - name of the share space to create
Throws:
XapException - in case of invalid share space name

loadApplication

public void loadApplication(com.virtualweaver.xotics.datamodel.XoDMInstance appDoc,
                            java.lang.String name,
                            java.util.Map parameters)
                     throws XapException
Loads an application, composed with an app document (XAPE APP dialect) and associated config parameters. the result is identified by param name which represents this loaded appli. the same document with different parameters yields to another application. The parameters are couples of name/value used to configure the loading process. Valid parameter names are : from XapConstants If param ACP_AUTO_LAUNCH is provided, this appli is also started.

Parameters:
appDoc - the XML document, in XAPE APP dialect
name - name of the application to load
parameters - a map containing loading parameters, as couples of name/value
Throws:
XapException
See Also:
XapConstants

sendRequest

public XapResponse sendRequest(XapRequest req)
                        throws XapException
Sends a request. If the target is unknown but valid, a new instance is created and started. This is also the way to start new instances. Thus, every XAPE processing starts from a call to this method. Then, for instances running in XapConstants.IN_CALLERS_THREAD, the thread calling this method is the running thread.

Parameters:
req - a request object containing target and content
Returns:
a response object containing response content.
Throws:
XapException
See Also:
XapRequest

createShutdownMessage

public static XapRequest createShutdownMessage(com.virtualweaver.xotics.datamodel.XoEnvironment env,
                                               java.lang.String appName,
                                               java.lang.String instanceName)
                                        throws XapException
Utility method to create a special message requesting the shutdown of a particular App instance. If Application is mono-instance, param instanceName is ignored.

Parameters:
env - current XO environment
appName - target Application name
instanceName - target instance name
Returns:
a newly created request object containing shutdown command
Throws:
XapException

createStartupMessage

public static XapRequest createStartupMessage(com.virtualweaver.xotics.datamodel.XoEnvironment env,
                                              java.lang.String appName,
                                              java.lang.String instanceName)
                                       throws XapException
Creates a special message requesting the launch of a new Instance, named instanceName, from a loaded Application identified by appName. If Application appName is mono-instance, instanceName is ignored, and if such mono-instance Application has already a running instance, this message is ignored.

Parameters:
env - current XO environment
appName - target Application name
instanceName - target instance name
Returns:
a newly created request object containing startup command
Throws:
XapException

createRequest

public static XapRequest createRequest(com.virtualweaver.xotics.datamodel.XoEnvironment env,
                                       byte type,
                                       java.lang.String appName,
                                       java.lang.String instanceName,
                                       java.lang.String handler,
                                       java.lang.String reqId,
                                       XapQueue responseQueue,
                                       com.virtualweaver.xotics.datamodel.XoObject contentObject)
                                throws XapException
This is a utility method to create a request object, root of an XML subtree dedicated to be integrated into the private context of an app instance. Here is its format :
 <ctx:request>
 	<ctx:content>
 		<any:contentObject>
 	</ctx:content>
 	<ctx:response>
 		<any:response-content>
	</ctx:response>
 </ctx:request>
where :

Parameters:
env - XO enviroment used by XAPE engine
type - type of request (REQ_TYPE_ONEWAY, REQ_TYPE_SYNC, REQ_TYPE_ASYNC) from XapConstants
appName - name of target application
instanceName - name of application instance, needed only to reach a specific instance of a multi-instance application
handler - optional id of a specific element to process directly (under a or element)
reqId - an optional ID to identify this request (if null, a reqId is created internally)
responseQueue - a queue object to receive response in case of a REQ_TYPE_ASYNC request and a target instance running in a dedicated thread (IN_DEDICATED_THREAD)
contentObject - an XO object or XO tree fragment representing the request content
Returns:
a newly created request object
Throws:
XapException - if some error occurs