com.orchestranetworks.service
Class ServiceContext

java.lang.Object
  com.orchestranetworks.service.ServiceContext

public abstract class ServiceContext

extends Object

This class provides the necessary context and navigation functions for integrating UI services into EBX.Manager. For general information, see UI Services.

Schema definition

A UI service must be declared as a complex type definition:

 <xs:complexType name="MyService"> 
   <xs:annotation> 
     <xs:appinfo> 
       <osd:service 
              resourcePath="/myFirstPage.jsp" 
              activatedForPaths="/a/b /a/c" /> 
     </xs:appinfo>
     <xs:documentation>
        My Service Label. My Service description.
    </xs:documentation>
   </xs:annotation> 
 </xs:complexType>

where MyService is the name that identifies the service, /myFirstPage.jsp is a resource existing in the module (Web application) and /a/b, /a/c specifies two elements in the schema instances.

Attribute	Description	Required
resourcePath	identifies the resource to call in the web application (that is, the EBX.Platform module attached to the schema). The path must begin with a "/" and is interpreted as relative to the web application root. See ServletContext.getRequestDispatcher(String).	Yes.
activatedForPaths	specifies where the service is available. The list of paths is white-space delimited. Each path must be the absolute XPath notation of the node. For osd:table, an additional syntax allows to specify whether the service is activated on the table globally or on occurrence(s) selection. If the path to the table is /root/myTable: /root/myTable activates the service on the table globally. /root/myTable{1} activates the service if one occurrence is selected. /root/myTable{2} activates the service if two occurrence are selected. /root/myTable{n} activates the service if exactly n occurrences are selected (n is a positive integer). /root/myTable{+} activates the service if one, two, ..., n occurrences are selected (unbounded selection).	No. Default will activate as a global service not attached to a particular node.
class	specifies a Java class that implements ServicePermission.	No. If not defined, service has no permission restriction.

Usage of this class

First of all, the JSP or the Servlet gets the current context by calling:

 ServiceContext.getServiceContext(HttpServletRequest)

For inserting URLs that will be interpreted by the Manager, the JSP/Servlet must call one the methods:

 ServiceContext.getURL...(...)

For updating the repository, for importing or exporting data, the JSP/Servlet must call the method:

 ServiceContext.execute(Procedure)

Example

See Tutorial.

See Also:

ServicePermission

Method Summary

abstract void	addMessage(UserMessage aMessage) Adds a message.
abstract ProcedureResult	execute(Procedure aProcedure) Executes the procedure specified.
abstract Adaptation	getCurrentAdaptation() Returns the adaptation currently selected in Manager.
abstract AdaptationHome	getCurrentHome() Returns the home currently selected in Manager.
abstract SchemaNode	getCurrentNode() Returns the schema node currently selected in Manager.
abstract Path	getCurrentPathInAdaptation() Returns the node path currently selected in Manager.
abstract Request	getCurrentRequest() Returns the request for the current table selected in EBX.Manager.
abstract Locale	getLocale() Returns the current Locale of Manager session.
abstract List	getSelectedOccurrences() Returns the occurrences currently selected in Manager.
static ServiceContext	getServiceContext(HttpServletRequest aRequest) Retrieves context instance from HTTP request attributes.
abstract String	getServiceDescription() Returns the description of the service, localized in session's current locale.
abstract String	getServiceLabel() Returns the label of the service, localized in session's current locale.
abstract Session	getSession() Returns the current session context.
abstract String	getURLForEndingService() Returns a Manager URL indicating that the execution of this service is finished.
abstract String	getURLForIncludingResource(String aResourcePath) Returns a Manager URL indicating that this service execution continues to the resource specified.
abstract String	getURLForResource(ResourceType aResourceType, String aResourceName) Returns the URL of the Web resource specified, in the current module and for the current session locale.
abstract String	getURLForResource(ResourceType aResourceType, String aResourceName, Locale aLocale) Returns the URL of the Web resource specified, in the current module (that is, the module of the current adaptation).
abstract String	getURLForResource(String aResourcePath) Returns the URL string for the resource specified.
abstract String	getURLForResource(String aModuleAliasOrName, ResourceType aResourceType, String aResourceName, Locale aLocale) Returns the URL of the Web resource specified.
abstract String	getURLForSelection(Adaptation anAdaptation) Returns a Manager URL indicating that it must select the adaptation (instance or occurrence) specified.
abstract String	getURLForSelection(Adaptation anAdaptation, Path aPath) Returns a Manager URL indicating that it must select the adaptation (instance or occurrence) and the node specified.
abstract boolean	isCalledOnHome() Returns true if the current service is called from a home menu.
abstract boolean	isCalledOnInstance() Returns true if the current service is called from an instance menu.
abstract boolean	isCalledOnOccurrencePage() Returns true if the current service is called from an occurrence page.
abstract boolean	isCalledOnTable() Returns true if the current service is called from the "Services on table" menu category.
abstract boolean	isCalledOnTableSelection() Returns true if the current service is called from the "Services on selected records" menu category.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getServiceContext

public static ServiceContext getServiceContext(HttpServletRequest aRequest)

Retrieves context instance from HTTP request attributes. This method won't return null only if we are in the context of a service execution (this means that Manager is performing a server-side include).

execute

public abstract ProcedureResult execute(Procedure aProcedure)

Executes the procedure specified. It calls in a transactional container the implementation of Procedure.execute(ProcedureContext).

Returns:

the result of the execution (particularly, whether it has thrown an exception).

getCurrentHome

public abstract AdaptationHome getCurrentHome()

Returns the home currently selected in Manager.

getCurrentAdaptation

public abstract Adaptation getCurrentAdaptation()
                                         throws IllegalStateException

Returns the adaptation currently selected in Manager.

This method returns an adaptation instance if :

• the current service is running from an instance menu (see isCalledOnInstance() ) ;
• the current service is running on a whole table, from "Services on table" menu category (see isCalledOnTable() ) ;
• the current service is running on a table selection, from "Services on selected records" menu category, and more than one occurrence is selected (see isCalledOnTableSelection() );

This method returns an adaptation occurrence if:

• the current service is running on a table selection and exactly one occurrence is selected (see isCalledOnTableSelection() );
• the current service is running on a page occurrence (see isCalledOnOccurrencePage() ).

Throws:

IllegalStateException - if the current service is running from a home menu (branch or version, see isCalledOnHome()).

See Also:

getSelectedOccurrences()

getCurrentRequest

public abstract Request getCurrentRequest()

Returns the request for the current table selected in EBX.Manager. Returns null if this service is called ouside a table context.

See Also:

isCalledOnTable()

getSelectedOccurrences

public abstract List getSelectedOccurrences()

Returns the occurrences currently selected in Manager.

Returns:

a List of Adaptation that correspond to the occurrences selected in the Manager, or an empty list if the service is being executed on an adaptation instance.

See Also:

isCalledOnTableSelection(), getCurrentAdaptation()

getCurrentNode

public abstract SchemaNode getCurrentNode()

Returns the schema node currently selected in Manager.

getCurrentPathInAdaptation

public abstract Path getCurrentPathInAdaptation()

Returns the node path currently selected in Manager.

getLocale

public abstract Locale getLocale()

Returns the current Locale of Manager session.

See Also:

Session.getLocale()

getSession

public abstract Session getSession()

Returns the current session context.

getServiceLabel

public abstract String getServiceLabel()

Returns the label of the service, localized in session's current locale.

The label of the service is specified in the schema document, under the node xs:annotation/xs:documentation.

getServiceDescription

public abstract String getServiceDescription()

Returns the description of the service, localized in session's current locale.

The description of the service is specified in the schema document, under the node xs:annotation/xs:documentation.

addMessage

public abstract void addMessage(UserMessage aMessage)

Adds a message. This message will be displayed in the standard message pane of Manager.

getURLForIncludingResource

public abstract String getURLForIncludingResource(String aResourcePath)

Returns a Manager URL indicating that this service execution continues to the resource specified.

The resource must be in the same web application as the service.

Parameters:

aResourcePath - path of the resource in its web application (it must not contain web application's specific path).

getURLForEndingService

public abstract String getURLForEndingService()

Returns a Manager URL indicating that the execution of this service is finished.

getURLForResource

public abstract String getURLForResource(String aResourcePath)

Returns the URL string for the resource specified.

The resource must be in the same web application as the service.

Parameters:

aResourcePath - must begin with a "/" and is interpreted as relative to the module (web application) root.

getURLForResource

public abstract String getURLForResource(ResourceType aResourceType,
                                         String aResourceName)

Returns the URL of the Web resource specified, in the current module and for the current session locale.

See Also:

getURLForResource(ResourceType, String, Locale), getLocale()

getURLForResource

public abstract String getURLForResource(ResourceType aResourceType,
                                         String aResourceName,
                                         Locale aLocale)

Returns the URL of the Web resource specified, in the current module (that is, the module of the current adaptation).

Throws:

UnsupportedOperationException - if the resource type is internal (not accessible from HTTP).

getURLForResource

public abstract String getURLForResource(String aModuleAliasOrName,
                                         ResourceType aResourceType,
                                         String aResourceName,
                                         Locale aLocale)
                                  throws ModuleNotFoundException

Returns the URL of the Web resource specified.

Throws:

UnsupportedOperationException - if the resource type is internal (not accessible from HTTP).

ModuleNotFoundException - if the alias or name specified does not correspond to a module.

getURLForSelection

public abstract String getURLForSelection(Adaptation anAdaptation)

Returns a Manager URL indicating that it must select the adaptation (instance or occurrence) specified.

getURLForSelection

public abstract String getURLForSelection(Adaptation anAdaptation,
                                          Path aPath)

Returns a Manager URL indicating that it must select the adaptation (instance or occurrence) and the node specified.

isCalledOnHome

public abstract boolean isCalledOnHome()

Returns true if the current service is called from a home menu.

See Also:

getCurrentHome()

isCalledOnInstance

public abstract boolean isCalledOnInstance()

Returns true if the current service is called from an instance menu.

See Also:

getCurrentAdaptation()

isCalledOnTable

public abstract boolean isCalledOnTable()

Returns true if the current service is called from the "Services on table" menu category.

In this case, it is generally expected that the service will apply on the whole table or on the filtered table.

See Also:

getCurrentRequest()

isCalledOnTableSelection

public abstract boolean isCalledOnTableSelection()

Returns true if the current service is called from the "Services on selected records" menu category.

In this case, it is generally expected that the service will apply on the selected occurrences.

See Also:

getSelectedOccurrences()

isCalledOnOccurrencePage

public abstract boolean isCalledOnOccurrencePage()

Returns true if the current service is called from an occurrence page.

In this case, it is generally expected that the service will apply on the current occurrence.

See Also:

getCurrentAdaptation()