Creating Contextual Portal Services

Generally, a portal service is not stateful, that is, it does not maintain information for the current page or user session. Each time an application asks for an instance of the service, the instance is not specific for the page or user session; the same instance may be used for many sessions and does not maintain information about the current session.

Regular vs. Contextual Portal Services

A regular portal service is defined by a portal application that contains the following:

Service Interface (public): Extends IService and defines custom methods.
Service Implementation (private): Implements the public service interface, which includes both IService and custom methods.

The portalapp.xml for the application defines the service by specifying a name for the service and the class to instantiate when the service is called, which is the service implementation.

An application asks for an instance of the service by providing a key, composed of the application name and the service name defined in the portalapp.xml. An instance of the service implementation is returned (exposed only as the interface), as shown below:

This graphic is explained in the accompanying text.

A contextual portal service maintains state information (or a context) for the life of the current portal user session.

A contextual portal service is defined by a portal application that contains the following:

Service Interface (public): Defines only custom methods (and does not extend IService).
Service Implementation (private): Implements IService, as well as IServiceInstanceCreator.
Service Instance (private): Implements the public interface (and, therefore, the custom methods), as well as IServiceInstance.

Just like a regular service, the portalapp.xml for the application defines a service, a name for the service, and the class to instantiate for the service, which is the service implementation.

An application asks for an instance of the service by providing a key, composed of the application name and the service name defined in the portalapp.xml. An instance of the service instance is returned (exposed only as the interface), as shown below:

This graphic is explained in the accompanying text.

When a Web Dynpro application running in an iView in the portal calls for an instance of a contextual portal service, a new instance of the service is returned to the application. The next time the application requests an instance of the service, the same instance is returned.

Note Note

A contextual portal service can only be called from a Web Dynpro application.

End of the note.

Prerequisites

In NetWeaver Developer Studio, you have created a portal application and portal service with the Portal Application creation wizard.
For a portal service, the wizard creates a public interface (in the src.api folder) and private implementation class (in the src.core folder).

The following procedure assumes that you have created the following:

Portal Application: myApp
Portal Service:
- Interface: ImyContextService
- Implementation: myContextService

Procedure

In ImyContextService, do the following:
1. In the class declaration, remove extends Iservice.
2. Set the value for the constant KEY.
  The service key is the fully qualified name of the service (myApp.myContextService).
3. Define the custom methods for the service.
Create a service instance class in the private section of your application (the src.core folder, which also holds myContextService).
The service instance is the implementation of the service interface that is returned when an application requests an instance of the service.

To create the instance class, do the following:
1. In the package folder that contains the myContextService, create a new class called myServiceInstance.
  Declare that the class implements ImyContextService and IServiceInstance. The following is the class declaration for myServiceInstance:
  Syntax
  1. public class myServiceInstance implements ImyContextService, IServiceInstance {}
  End of the code.
2. Implement all the custom methods for the service, as defined by the ImyContextService interface.
3. Implement the following method defined by the IServiceInstance interface:
  - isInitiated(): Return true.
    
    Syntax
    public boolean isInitiated() { return true; }
    
    End of the code.
In myContextService, do the following:
1. In the class declaration, remove implements ImyContextService and, instead, declare that the class implements IServiceInstanceCreator and IService.
2. Implement the IServiceInstanceCreator methods, which are the following:
  - newInstance(): Create and return a new instance of your service instance (IserviceInstance).
    
    Syntax
    public IServiceInstance newInstance() { return new MyServiceInstance(); }
    
    End of the code.
  - releaseInstances(): This can be an empty implementation.
    
    Syntax
    public void releaseInstances(IServiceInstance ctxService) {}
    
    End of the code.
3. In the getKey() method, return ImyContextService.KEY (instead of simply KEY).
In the portalapp.xml, do the following:
1. Create a sharingreference to com.sap.portal.fpn.api.servicegateway.
2. To the <registry> element , add an <entry> element with the following attributes:
  - path: /com.sap.portal.fpn.api.servicegateway/services/<full name of service>
  - name: full name of service
  - type: service
  The following is the <registry> section for the myApp application:
  Syntax
  1. <registry>
  2. <entry path="/com.sap.portal.fpn.api.servicegateway/services/ContextServiceApp.myContextService" name="ContextServiceApp.myContextService" type="service"/>
  3. </registry>
  End of the code.
Deploy the application.