com.virtualweaver.xotics.dialect.xape.engine
Interface XapRuntimeEnvironment

All Superinterfaces:
java.lang.Cloneable

public interface XapRuntimeEnvironment
extends java.lang.Cloneable

This class represents an execution environment for XAPE application processing. It provides useful methods to access data and functions of the Engine. An environment is instanciated for each application instance.

Version:
2.1

Method Summary
 void addXPathVariable(java.lang.String name, java.lang.Object value)
          Adds an new XPath variable.
 com.virtualweaver.xotics.datamodel.XoDMInstance bindDmdl(java.lang.String sharespace, java.lang.String docName, java.lang.String nsref, boolean force)
          Loads the DMDL document for a specific namespace nsref into a specific share space or in the private space.
 com.virtualweaver.xotics.datamodel.XoDMInstance bindDocument(java.lang.String sharespace, java.lang.String docName, java.net.URL url, java.util.Map initOptions, java.lang.Object initObject, boolean force)
          loads a document into a specific share space or in the private space.
 com.virtualweaver.xotics.datamodel.XoDMInstance bindDocument(java.lang.String sharespace, java.lang.String docName, com.virtualweaver.xotics.datamodel.XoDMInstance doc, java.util.HashMap initOptions, java.lang.Object initObject, boolean force)
          loads a document into a specific share space or in the private space.
 java.lang.Object clone()
           
 com.virtualweaver.xotics.datamodel.XoDMInstance createDocument(java.lang.String sharespace, java.lang.String docName, java.lang.String nsref, java.lang.String prefix, java.lang.String element, java.util.Map initOptions, java.lang.Object initObject, boolean force)
          Creates a document into a specific share space or in the private space.
 void debug(java.lang.String id, java.lang.String element, java.lang.String message)
           
 java.lang.String getApplicationName()
          Accessor for the current application name
 java.lang.String[] getApplicationNames()
          Return the name of each application loaded by the Engine
 java.net.URL getBaseUrl()
          Accessor for specified base URL, if any.
 java.lang.String getCurrentState()
          Accessor for the current state
 com.virtualweaver.xotics.datamodel.XoDMInstance getDocument(java.lang.String sharespace, java.lang.String docName)
          Returns the XO DM instance for XML document named docName in the share space sharespace.
 com.virtualweaver.xotics.datamodel.XoDMInstance getDocument(XapDocumentId did)
          Returns the XO DM instance for XML document designated by did.
 XapDocumentId[] getDocumentNames()
          Returns the full list of documents accessible to XAPE instance using this.
 java.lang.String getInstanceName()
          Accessor for the current instance name.
 java.lang.String[] getInstanceNames(java.lang.String appName)
          Returns the list of instances of application named appName currently running.
 java.lang.String getNextState()
          Accessor for the next state, which will become the current state at next iteration.
 java.lang.String[] getShareSpaceNames()
          Returns the full list of existing share spaces.
 com.virtualweaver.xotics.datamodel.XoEnvironment getXoEnvironment()
          Accessor to the current XO environment
 com.virtualweaver.xotics.datamodel.XoNode getXPathContextNode()
          This runtime environment can compute XPath requests, and stores at any time a context node.
 java.util.Map getXPathVariables()
          Returns XPath variables currently stored by this, and used in every XPath request computed by this.
 boolean isMultiInstances(java.lang.String appName)
          Tells whether this application is multi instances or not
 void log(java.lang.String id, java.lang.String element, java.lang.String message)
           
 void reloadApplication(java.lang.String name)
          Ask Engine to update a XAPE application (named name) at run-time, by reloading its main application document.
 void removeXPathVariable(java.lang.String name)
          Removes XPath variable identified by param name form the list of stored variables.
 java.net.URL resolveUrl(java.lang.String url)
          From a string param url representing a relative or absolute URL, returns an absolute URL.
 java.lang.String resolveValue(java.lang.String val)
          In any XAP application arguments of type string, a string can contain XPath request parts enclosed by '{}' which are resolved by this method into strings.
 XapResponse sendRequest(XapRequest req)
          Sends a request to be processed by the Engine.
 void setNextState(java.lang.String state)
          Sets the next state.
 void setXPathContextNode(com.virtualweaver.xotics.datamodel.XoNode node)
          Sets the current XPath context node, used in every XPath request computed by this.
 void unbindDocument(java.lang.String sharespace, java.lang.String docName, boolean release)
          Removes the document named docName either from a specific share space identified by sharespace or from the private space.
 com.virtualweaver.xotics.datamodel.XoDataType xpathRequest(java.lang.String req)
          Computes an XPath request defined by param req.
 com.virtualweaver.xotics.datamodel.XoNode[] xpathRequestNodes(java.lang.String req)
          The same method as xpathRequest() excepted that result is filtered to show XoNode objects only.
 

Method Detail

getXoEnvironment

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

Returns:
current XO environment

getInstanceName

public java.lang.String getInstanceName()
Accessor for the current instance name. For mono-instance applications, this method returns the application name.

Returns:
current instance name

reloadApplication

public void reloadApplication(java.lang.String name)
                       throws XapException
Ask Engine to update a XAPE application (named name) at run-time, by reloading its main application document.

Parameters:
name - name of the application to update
Throws:
XapException

getApplicationName

public java.lang.String getApplicationName()
Accessor for the current application name

Returns:
current application name

getApplicationNames

public java.lang.String[] getApplicationNames()
                                       throws XapException
Return the name of each application loaded by the Engine

Returns:
a string array containing all loaded application names
Throws:
XapException

isMultiInstances

public boolean isMultiInstances(java.lang.String appName)
                         throws XapException
Tells whether this application is multi instances or not

Parameters:
appName - name of an application
Returns:
true if app is multi instances
Throws:
XapException

getBaseUrl

public java.net.URL getBaseUrl()
Accessor for specified base URL, if any.

Returns:
the base URL specified at loading time, or null if no value was given

resolveUrl

public java.net.URL resolveUrl(java.lang.String url)
                        throws XapException
From a string param url representing a relative or absolute URL, returns an absolute URL.

Parameters:
url - a relative or absolute url string
Returns:
an absolute URL
Throws:
XapException - if some error occurs during resolution

getCurrentState

public java.lang.String getCurrentState()
Accessor for the current state

Returns:
the current state

getNextState

public java.lang.String getNextState()
Accessor for the next state, which will become the current state at next iteration.

Returns:
the next state, the current state by default

setNextState

public void setNextState(java.lang.String state)
Sets the next state. If this method is not used, next state remains current state

Parameters:
state - the state to jumpt to at next iteration

getXPathContextNode

public com.virtualweaver.xotics.datamodel.XoNode getXPathContextNode()
This runtime environment can compute XPath requests, and stores at any time a context node. By default, this method returns null, which is interpreted in XPath requests as the root node (i.e. an XoDMInstance).

Returns:
current context node, or null if not set

setXPathContextNode

public void setXPathContextNode(com.virtualweaver.xotics.datamodel.XoNode node)
Sets the current XPath context node, used in every XPath request computed by this.

Parameters:
node - any XO object implementing XoNode (XoDMInstance, XoObject, XoProperty)

getXPathVariables

public java.util.Map getXPathVariables()
Returns XPath variables currently stored by this, and used in every XPath request computed by this. An XPath variable is a couple (name, value), where name is a string, and value is any object convertible into XsdDataType.

Returns:
a map containing variables as couples of name and value

addXPathVariable

public void addXPathVariable(java.lang.String name,
                             java.lang.Object value)
Adds an new XPath variable. Replaces a possible existing variable by this new one.

Parameters:
name - variable name
value - variable value

removeXPathVariable

public void removeXPathVariable(java.lang.String name)
Removes XPath variable identified by param name form the list of stored variables.

Parameters:
name - name of the variable to remove

getDocument

public com.virtualweaver.xotics.datamodel.XoDMInstance getDocument(java.lang.String sharespace,
                                                                   java.lang.String docName)
                                                            throws XapException
Returns the XO DM instance for XML document named docName in the share space sharespace. To get documents in the private space, set param sharespace to null.

Parameters:
sharespace - a share space name or null to get documents of private space
docName - the document name
Returns:
corresponding DM instance or null if not found
Throws:
XapException - for any error occurrence

getDocument

public com.virtualweaver.xotics.datamodel.XoDMInstance getDocument(XapDocumentId did)
                                                            throws XapException
Returns the XO DM instance for XML document designated by did.

Parameters:
did - the document full ID (sharespace + name)
Returns:
corresponding DM instance or null if not found
Throws:
XapException - for any error occurrence

getDocumentNames

public XapDocumentId[] getDocumentNames()
                                 throws XapException
Returns the full list of documents accessible to XAPE instance using this.

Returns:
an array of document IDs made of couples of share space / document name.
Throws:
XapException - for any error occurrence

getShareSpaceNames

public java.lang.String[] getShareSpaceNames()
                                      throws XapException
Returns the full list of existing share spaces.

Returns:
an array of string containing share space names
Throws:
XapException - for any error occurrence

sendRequest

public XapResponse sendRequest(XapRequest req)
                        throws XapException
Sends a request to be processed by the Engine. This method allows any XAPE instance to launch or communicate with any other application instance.

Parameters:
req - a request to send
Returns:
teh response if any
Throws:
XapException - for any error occurrence

getInstanceNames

public java.lang.String[] getInstanceNames(java.lang.String appName)
                                    throws XapException
Returns the list of instances of application named appName currently running.

Parameters:
appName - application name
Returns:
running instance names of this application
Throws:
XapException

bindDocument

public com.virtualweaver.xotics.datamodel.XoDMInstance bindDocument(java.lang.String sharespace,
                                                                    java.lang.String docName,
                                                                    java.net.URL url,
                                                                    java.util.Map initOptions,
                                                                    java.lang.Object initObject,
                                                                    boolean force)
                                                             throws XapException
loads a document into a specific share space or in the private space.

Parameters:
sharespace - a share space container or null to refer to the private space
docName - name of the document to load
url - location of the XML document to load
initOptions - optional map containing init options for XO loading (XoFactory.loadDMInstance())
initObject - optional object specific to the document loading process
force - when true, replaces any document already bound with same (sharespace, docName) ID, otherwise an exception is thrown in such case
Returns:
a DM instance
Throws:
XapException - if loading fails or if a document is already bound with same (sharespace, docName) ID

bindDocument

public com.virtualweaver.xotics.datamodel.XoDMInstance bindDocument(java.lang.String sharespace,
                                                                    java.lang.String docName,
                                                                    com.virtualweaver.xotics.datamodel.XoDMInstance doc,
                                                                    java.util.HashMap initOptions,
                                                                    java.lang.Object initObject,
                                                                    boolean force)
                                                             throws XapException
loads a document into a specific share space or in the private space.

Parameters:
sharespace - a share space container or null to refer to the private space
docName - name of the document to load
doc - DM instance to bind to current Instance
initOptions - optional map containing init options for XO loading (XoFactory.loadDMInstance())
initObject - optional object specific to the document loading process
force - when true, replaces any document already bound with same (sharespace, docName) ID, otherwise an exception is thrown in such case
Returns:
a DM instance
Throws:
XapException - if loading fails or if a document is already bound with same (sharespace, docName) ID

bindDmdl

public com.virtualweaver.xotics.datamodel.XoDMInstance bindDmdl(java.lang.String sharespace,
                                                                java.lang.String docName,
                                                                java.lang.String nsref,
                                                                boolean force)
                                                         throws XapException
Loads the DMDL document for a specific namespace nsref into a specific share space or in the private space.

Parameters:
sharespace - a share space container or null to refer to the private space
docName - name of the document to load
nsref - namespace of the dialect whose DMDL document is to load
force - when true, replaces any document already bound with same (sharespace, docName) ID, otherwise an exception is thrown in such case
Returns:
a DM instance in DMDL format
Throws:
XapException - if loading fails or if a document is already bound with same (sharespace, docName) ID

createDocument

public com.virtualweaver.xotics.datamodel.XoDMInstance createDocument(java.lang.String sharespace,
                                                                      java.lang.String docName,
                                                                      java.lang.String nsref,
                                                                      java.lang.String prefix,
                                                                      java.lang.String element,
                                                                      java.util.Map initOptions,
                                                                      java.lang.Object initObject,
                                                                      boolean force)
                                                               throws XapException
Creates a document into a specific share space or in the private space.

Parameters:
sharespace - a share space container or null to refer to the private space.
docName - name of the document to create
nsref - namespace of the root element
prefix - NS prefix for root element
element - root element name
initOptions - optional map containing init options for XO creating (XoFactory.createDMInstance())
initObject - optional object specific to the document creating process
force - when true, replaces any document already bound with same (sharespace, docName) ID, otherwise an exception is thrown in such case
Returns:
a DM instance newly created
Throws:
XapException - if creation process fails or if a document is already bound with same (sharespace, docName) ID

unbindDocument

public void unbindDocument(java.lang.String sharespace,
                           java.lang.String docName,
                           boolean release)
                    throws XapException
Removes the document named docName either from a specific share space identified by sharespace or from the private space.

Parameters:
sharespace - share space of the document to remove ; a null avalue identifies the private space
docName - the document name
release - if true, a call to XoDMInstance.release() is performed after removal
Throws:
XapException - if remove operation fails

xpathRequest

public com.virtualweaver.xotics.datamodel.XoDataType xpathRequest(java.lang.String req)
                                                           throws XapException
Computes an XPath request defined by param req. In XAPE, such XPath request can be prefixed by the function doc() which specify the target document for the request. These formats are allowed : doc(sharespace#docname) or doc(docname). Missing sharespace means private space. Missing doc() function identifies the application document where the request is written.

Parameters:
req - the XPath request
Returns:
XPath result
Throws:
XapException - on any XPath request error

xpathRequestNodes

public com.virtualweaver.xotics.datamodel.XoNode[] xpathRequestNodes(java.lang.String req)
                                                              throws XapException
The same method as xpathRequest() excepted that result is filtered to show XoNode objects only. It's a utility method to retreive nodes.

Parameters:
req - the XPath request
Returns:
an XPath result as a list of XO nodes
Throws:
XapException - on any XPath request error

resolveValue

public java.lang.String resolveValue(java.lang.String val)
                              throws XapException
In any XAP application arguments of type string, a string can contain XPath request parts enclosed by '{}' which are resolved by this method into strings. Consider the value of an attribute of some application processing element :

"this is a {doc(doc1)//process[1]/@val} string"

If @val is "dynamic", the initial string becomes once resolved :

"this is a dynamic string". Unresolved parts are left as is.

Parameters:
val - the string to resolve
Returns:
the resolved string
Throws:
XapException - on any XPath request error

debug

public void debug(java.lang.String id,
                  java.lang.String element,
                  java.lang.String message)

log

public void log(java.lang.String id,
                java.lang.String element,
                java.lang.String message)

clone

public java.lang.Object clone()