Beruflich Dokumente
Kultur Dokumente
Release 6.0
June, 2003
Table of Contents:
1 PORTAL RUNTIME TECHNOLOGY .........................................................................................................................6
INTRODUCTION AND POSITIONING ...........................................................................................................................................6
CONCEPTS AND TERMINOLOGY ...............................................................................................................................................7
Portal Environment ............................................................................................................................................................7
Portal Application ..............................................................................................................................................................7
Portal Application Archive (PAR files)...............................................................................................................................7
Portal Components .............................................................................................................................................................7
Portal Services....................................................................................................................................................................7
Portal Component Profile...................................................................................................................................................7
Portal Component Config...................................................................................................................................................7
Portal Runtime Mode..........................................................................................................................................................7
Portal Object Model (P.O.M.) ............................................................................................................................................7
Application Repository .......................................................................................................................................................8
2 PORTAL INFRASTRUCTURE .....................................................................................................................................9
PACKAGING .............................................................................................................................................................................9
CORE APPLICATIONS ...............................................................................................................................................................9
3 PORTAL RUNTIME API .............................................................................................................................................11
COMPONENT ..........................................................................................................................................................................11
IPortalComponent ............................................................................................................................................................11
AbstractPortalComponent ................................................................................................................................................12
SERVICE ................................................................................................................................................................................12
IService .............................................................................................................................................................................12
IServiceContext.................................................................................................................................................................12
REQUEST/RESPONSE ..............................................................................................................................................................13
IPortalComponentRequest................................................................................................................................................13
IPortalComponentResponse .............................................................................................................................................13
4 PORTAL APPLICATION ARCHIVES.......................................................................................................................14
PAR FILE FORMAT ................................................................................................................................................................14
Web Resources..................................................................................................................................................................14
Non-Web Resources..........................................................................................................................................................14
PAR BUILDING .....................................................................................................................................................................15
STRUCTURE OF THE DEPLOYMENT DESCRIPTOR....................................................................................................................16
PORTAL APPLICATION ...........................................................................................................................................................16
Portal Application Configuration.....................................................................................................................................16
PORTAL COMPONENTS ..........................................................................................................................................................18
Portal Component Configuration .....................................................................................................................................18
Portal Component Profiles ...............................................................................................................................................19
PORTAL SERVICES .................................................................................................................................................................21
Portal Service Configuration Properties ..........................................................................................................................22
Portal Service Profiles......................................................................................................................................................22
5 PORTAL APPLICATION LIFE CYCLE....................................................................................................................23
OVERVIEW ............................................................................................................................................................................23
APPLICATION DEPENDENCIES................................................................................................................................................24
HOT DEPLOYMENT ................................................................................................................................................................24
6 PORTAL RUNTIME ARCHITECTURE....................................................................................................................25
REQUEST DISPATCHER ..........................................................................................................................................................25
Dispatcher API .................................................................................................................................................................26
Dispatching a Request ......................................................................................................................................................26
PORTAL RUNTIME API ..........................................................................................................................................................27
PORTAL RUNTIME CORE........................................................................................................................................................27
PORTAL REGISTRY ................................................................................................................................................................30
Central Configuration Storage .........................................................................................................................................30
PORTAL RUNTIME CACHE .....................................................................................................................................................31
Properties .........................................................................................................................................................................31
API....................................................................................................................................................................................31
Caching Expiration...........................................................................................................................................................31
PORTAL APPLICATION REPOSITORY ......................................................................................................................................32
PORTAL CONNECTION FRAMEWORK .....................................................................................................................................32
7 REQUEST CYCLE ........................................................................................................................................................34
NODE.....................................................................................................................................................................................34
PORTAL COMPONENT MODE .................................................................................................................................................35
Accessing to a Mode .........................................................................................................................................................35
Mode Handling .................................................................................................................................................................35
PORTAL HOOKS .....................................................................................................................................................................37
Purpose.............................................................................................................................................................................37
Adding a new Portal Hook ...............................................................................................................................................38
Default hooks....................................................................................................................................................................39
EVENT HANDLING .................................................................................................................................................................40
Internal Portal Runtime Events ........................................................................................................................................40
Request Event API ............................................................................................................................................................40
Component Event API.......................................................................................................................................................41
Event Handling .................................................................................................................................................................41
8 JNDI SUPPORT IN PRT...............................................................................................................................................42
PRT JNDI SUPPORT PACKAGE..............................................................................................................................................42
JNDI Service Providers ....................................................................................................................................................42
JNDI Clients .....................................................................................................................................................................43
JNDI Service Providers Packaging ..................................................................................................................................43
JNDI Provider Resource File Sample...............................................................................................................................44
JNDI CONCEPTS AND RELATED DOCUMENTS .......................................................................................................................44
JNDI Environment............................................................................................................................................................44
JNDI Context ....................................................................................................................................................................44
JNDI Context Factories....................................................................................................................................................45
9 WEB SERVICES SUPPORT ........................................................................................................................................46
APPROACH ............................................................................................................................................................................46
Portal Services as WEB Services......................................................................................................................................46
Portal Applications and external WEB services ...............................................................................................................46
CONCEPTS .............................................................................................................................................................................47
ARCHITECTURE .....................................................................................................................................................................48
10 PAR IDE......................................................................................................................................................................53
APPROACH ............................................................................................................................................................................53
ADDITIONAL FEATURE ..........................................................................................................................................................53
11 COMPATIBILITY CONSIDERATIONS................................................................................................................56
EP 5.0 BACKWARD COMPATIBILITY ......................................................................................................................................56
EP50 Deployment Policy..................................................................................................................................................56
EP50 Class Loading .........................................................................................................................................................56
EP50 Archives ..................................................................................................................................................................56
LIST OF INCOMPATIBILITIES TO EP 5.0 ..................................................................................................................................57
UNIX/WINDOWS COMPATIBILITY .........................................................................................................................................57
12 ADDITIONAL PRT SERVICES ..............................................................................................................................58
NOTIFICATION SERVICE.........................................................................................................................................................58
CONTENT CONVERSION SERVICE ..........................................................................................................................................59
CONTENT CONVERTER SERVICE ............................................................................................................................................60
JCO CLIENT SERVICE ............................................................................................................................................................61
RFC ENGINE SERVICE (UNDER CONSTRUCTION) ..................................................................................................................63
Service Description...........................................................................................................................................................63
Implementation .................................................................................................................................................................64
Security Open Issues.........................................................................................................................................................64
13 CONFIGURATION MANAGEMENT IN PORTAL APPLICATION.................................................................65
CREATE A CONFIG ARCHIVE .................................................................................................................................................66
Place your configuration files in folders ..........................................................................................................................66
Important Points ...............................................................................................................................................................66
Use Export PAR File of the PAR IDE...............................................................................................................................66
Config Archive properties file...........................................................................................................................................67
ACCESS DATA ........................................................................................................................................................................68
Modify portalapp.xml .......................................................................................................................................................68
Virtual Components ..........................................................................................................................................................68
Sharing Configuration between Applications ...................................................................................................................69
USE THE CONFIG FRAMEWORK API ......................................................................................................................................69
CONFIGURATION EVENT SUBSCRIPTION ................................................................................................................................70
Implement the interface IConfigEventListener .................................................................................................................70
Add a listener....................................................................................................................................................................72
Remove listener.................................................................................................................................................................72
START THE CONFIG MODE.....................................................................................................................................................72
14 EXCEPTION HANDLING........................................................................................................................................73
ISSUE OVERVIEW...................................................................................................................................................................73
CODING RULES ......................................................................................................................................................................73
Always pass the original exception...................................................................................................................................73
Always include a message ................................................................................................................................................73
Do not make wrong assumptions ......................................................................................................................................73
Do not have empty exception handlers .............................................................................................................................74
Do not only print the stack trace ......................................................................................................................................74
Log Important Exception ..................................................................................................................................................74
ADDING EXTRA INFORMATION ..............................................................................................................................................75
Log Viewer........................................................................................................................................................................75
Exception Files .................................................................................................................................................................75
Exception Catalog ............................................................................................................................................................76
15 APPENDIX..................................................................................................................................................................77
PAR FLOW ............................................................................................................................................................................77
Uploading a PAR File to the Application Repository.......................................................................................................77
Deploying a PAR File on all PRT Nodes..........................................................................................................................77
Local Deployment Consistency.........................................................................................................................................77
Deployment Policy............................................................................................................................................................78
DEPLOYMENT HOOK .............................................................................................................................................................79
TEXT LOCALIZATION AND PORTAL COMPONENTS INTERNATIONALIZATION ..........................................................................80
Principle and approach ....................................................................................................................................................80
API....................................................................................................................................................................................80
Resource Bundle Name.....................................................................................................................................................80
Locale lookup ...................................................................................................................................................................81
Resource Bundle packaging .............................................................................................................................................81
Portal Component Java Code...........................................................................................................................................82
Request/Response handling ..............................................................................................................................................82
JSP Support ......................................................................................................................................................................82
PERMISSION MODEL FOR PORTAL COMPONENTS AND PORTAL WEB SERVICES ....................................................................83
Security Zone ....................................................................................................................................................................83
Safety level........................................................................................................................................................................84
Implementation .................................................................................................................................................................84
Recommendations.............................................................................................................................................................85
PORTAL OBJECT NAME AND ALIAS .......................................................................................................................................86
Name.................................................................................................................................................................................86
Alias..................................................................................................................................................................................86
Example ............................................................................................................................................................................87
DIRECTORY STRUCTURE ........................................................................................................................................................88
Local Deployment Overview.............................................................................................................................................88
Local Deployment of Portal Applications.........................................................................................................................88
ELEMENTS OF A PORTAL APPLICATION .................................................................................................................................89
CLASS LOADING IN THE PORTAL RUNTIME ...........................................................................................................................90
Class Loading Examples...................................................................................................................................................90
DEPLOYMENT DESCRIPTOR EXAMPLE ...................................................................................................................................92
Application Example.........................................................................................................................................................93
CENTRAL CONFIGURATION STORAGE – HOW TO...................................................................................................................94
How to get the sub context that belongs to the application? ............................................................................................94
How to store and retrieve config files to/from the central location? ................................................................................94
SAP J2EE INTEGRATION AND INTERACTION .........................................................................................................................96
Executing a Servlet as a Portal Component. ....................................................................................................................96
Accessing to the Portal Service from a J2EE object.........................................................................................................96
PORTAL CONTENT ABSTRACTION .........................................................................................................................................97
JNDI Basis........................................................................................................................................................................97
JNDI Service Providers ....................................................................................................................................................97
Starting Portal Objects .....................................................................................................................................................97
PORTAL RUNTIME HELP MODE .............................................................................................................................................98
PORTAL RUNTIME TEST MODE ............................................................................................................................................100
LOGGER CONFIGURATION ....................................................................................................................................................101
JSP SUPPORT.......................................................................................................................................................................102
Declaring JSP as Portal Component..............................................................................................................................102
JSP selected programmatically ......................................................................................................................................102
JSP packaging/Compilation ...........................................................................................................................................103
Class Loader consideration............................................................................................................................................103
Supported Features in the PRT.......................................................................................................................................103
Portal Runtime extension................................................................................................................................................105
Tag lib packaging ...........................................................................................................................................................106
Java Beans......................................................................................................................................................................107
Handling Request Events................................................................................................................................................108
ASYNCHRONOUS RESPONSE API.........................................................................................................................................109
INDEX ...................................................................................................................................................................................112
1 Portal Runtime Technology
So, the Portal Runtime clearly positions itself as one of the key block used to build and execute any kind of
Portal.
The Portal Runtime defines and manages two kinds of objects that define a Portal Application. They are:
• Portal Components. From a user point of view, a component that can be displayed into a portal
page. From an application development perspective, a plug able component designed to be
executed into a Portal environment.
• Portal Services. A Component offering a globally accessible function in the Portal. The portal
runtime development model offers a way to implement a clear separation between a Service API
and its implementation.
Portal Environment
From the PRT perspective, a Portal environment is a Web site that serves as a starting point to information,
services and applications on the Internet or the Intranet.
Portal Application
The Portal Runtime technology defines an environment in which Portal Application are deployed,
instantiated, accessed and finally released. The Portal Runtime offers tools to facilitate the construction of
Portal Applications.
Portal Components
This is an executable part of the Portal Application. It can be described as a Java Code defined by properties
and executed in a particular mode. It can also be a JSP.
Portal Services
It is a service offering functionality to other applications of the portal.
Packaging
The Portal Runtime relies on the J2EE architecture implemented by the SAP J2EE Application Server. As a
result the Portal Runtime is packaged in an EAR file called IRJ (iView Runtime for Java).
The IRJ file contains 3 main parts:
• Libraries and configuration files. The Portal Runtime and its configuration.
• Core applications. The core services of the Portal Runtime.
• Applications. Additional Portal Applications.
In addition to the IRJ file, the Portal Runtime infrastructure delivers a SAP J2EE service containing all the
PRT functionalities and services relying on specific SAP J2EE implementation called PRT bridge as shown
in the figure below.
Portal Runtime
Other servlets
Applications
Core Applications
The Portal Infrastructure relies on a predefined set of applications to provide core functionalities in the Portal
infrastructure. This set of applications, called core applications are ensured to be loaded before any other
applications when the Portal is initialized. Those applications are also never loaded in the Application
repository.
On the contrary, a regular application is started only when required, either because the application has been
marked as “load on startup”, or because an element of the application is requested to be executed.
Concerning the application storage, non-core applications are always loaded in the Application Repository.
Component
IPortalComponent
This is the central abstraction of the Portal Component API. All Portal Components implement this interface
either directly or by extending the AbstractPortalComponent helper class. The Portal Runtime calls the
following methods during the Portal Component’s life cycle
• Init() The Portal Component is created and loaded in the execution environment and then
initialized with the init(). The Portal always initializes one instance of the Portal Component and this
instance is shared among different users and sessions.
• Service() The service() method is called when the Portal Component is asked to process the
client’s request.
AbstractPortalComponent
The AbstractPortalComponent provides default behavior for Portal Components. It is recommended to inherit
from this class when developing a Portal Component. However, the Portal Runtime will never make the
assumption that a Portal Component needs to be a subclass of the AbstractPortalComponent class.
The logic included in this class implements the default behavior
1. to handle the Portal Modes defined by the Portal Runtime like the Edit, Help and About mode. For
example accessing a Portal Component in the default mode will invoke the doContent() method of
the AbstractPortalComponent. In the same way, the doEdit() method is bound to the Edit Mode.
2. to dispatch and handle portal events, as well as request events.
The Abstract Portal Component implements also a interface called IPortalComponentInit to be notified of
its initialization. The Portal Runtime calls then the following method
• init(IPortalComponentInitContext) The Portal Component has an access to its configuration
defined in the portalapp.xml file. It also gains information about the application it belongs to.
Service
IService
Every objects that want to act as a Portal Service must implement the IService interface. The Portal Runtime
is responsible for the creation, load and destroy of Objects implementing this interface. During the life cycle
of a Portal Service, the Portal Runtime calls the following methods:
• init(IServiceContext) The init method is called when the Portal Service is loaded in memory.
When a Portal Service is referencing another Service, this service is then also loaded and initialized
by calling its init() method.
• afterInit() The afterInit() method is called when the init method returns. This allows a
Portal Service to be notified when the initialization chain is over. In a situation where several init()
methods are invoked, the Portal Runtime ensures that the afterInit() method is called when all the
init() methods are ended.
• destroy() The destroy() method is called when the Service is stopped and discarded
from memory.
IServiceContext
The IServiceContext gives to the Portal Service a view on the Portal Environment in which it is executed.
The PortalServiceContext provides access to the Resources.
• getResource() Returns a IResource object representing a resource.
• getLogger() Returns the ILogger implementation to log information.
• getProfile() The getProfile() method returns a IServiceProfile instance representing the
Profile of the Service. The profile can be customized by the administrator.
• getConfiguration() The getConfiguration method provides a read-only access to the
IServiceConfig of the Service.
IPortalComponentRequest
This IPortalComponentRequest is passed to the PortalComponent thought the service() method or the
doContent() method, It contains request specific data and it provides access to the environment in which the
Portal Component is running.
The following Objects are accessible through the request:
• ServletConfig, HttpServletRequest, HttpServletResponse. Those objects are the original servlet
objects. In general accessing those objects is not recommended. But it is still permitted for very
specific actions.
• IPortalComponentSession, IUserContext, Locale. Objects offering user’s information.
• IPortalComponentContext. The context in which the current Portal Component is executed
• IRessource. A representation of an external resource.
• ILogger. A ILogger implementation to write information to the logs of the Portal.
• IPortalComponentProfile. The profile of the component.
In addition, the IPortalComponentRequest interface acts as a factory for URLs that the component would
have to generate (create component URI, request events…). The underlying default implementation of the
request is thread safe.
IPortalComponentResponse
The IPortalComponentResponse is given to the Portal Component through the service() method or the
through the specific mode handler methods. It encapsulates all the information, returned to the client from
the Portal Component. The following operations are provided through the response:
• addCookies() add a cookie in the response.
• write() Write a string in a response
• include() Include the content of another Portal Component into the response or a resource.
Web Resources
These are all file-based resources that are supposed to be accessible via http(s) requests to a web server
that provides access to the Portal. In a PAR file, all files that are NOT under PORTAL-INF fall into this
category.
Non-Web Resources
All files that are under the PORTAL-INF folder of the PAR file are not accessible via an http(s) request to the
portal.
Within the non-web resources a few folders and files have a special meaning:
Folder meaning
PORTAL-INF/lib This folder contains all the library files (JAR) that contain definitions of JAVA
classes and other class loader relevant resources (e.g. ResourceBundles) that can
be shared by referencing Portal Applications.
PORTAL-INF/classes This folder contains all class files and other files that define JAVA classes and other
class loader relevant resources (e.g. ResourceBundles), that can be shared by
referencing Portal Applications.
PORTAL- This folder contains all library files (JAR) that contain definitions of JAVA classes
INF/private/lib and other class loader relevant resources (e.g. ResourceBundles) are used
exclusively by the application.
PORTAL- This folder contains all class files and other files that define JAVA classes and other
INF/private/classes class loader relevant resources (e.g. ResourceBundles), that are used exclusively
by the application.
File Meaning
PORTAL- The XML file containing the Deployment Descriptor of the Portal Application. The
INF/portalapp.xml deployment descriptor describes all Application Entities of the application as far as
the runtime is concerned. It is described more precisely below.
META- The manifest file of the Portal Archive. It contains versioning and origin information.
INF/manifest.mf
<Portal Archive>
|
+-- META-INF
+-- MANIFEST.MF
+-- images
+-- scripts
+-- ...
|
+-- PORTAL-INF Non-WEB resources
| |
| +-- portalapp.xml
| |
| +-- lib API: jar files only
| +-- classes API: classes only
| |
+-- private
+-- lib CORE: jar files only
+-- classes CORE: classes only
PAR Building
The Portal Runtime offers two facilities to build a PAR file.
• A SAP Java IDE plugin called PAR Open Tool. This tool allows to
1. Read a PAR file and create a project.
2. Write a PAR file from a project.
• An Ant task accessible from the SAP Java IDE or from the Ant command prompt.
Portal Application
Within the application element the following child elements are allowed:
Example:
<application alias="com.abc.my.other.name">
<application-config>
...
</application-config>
<services>
...
</services>
<components>
...
</components>
</application>
The following properties are mainly kept for backward compatibility with 5.0. In general see also
Compatibility Considerations.
Each component section may contain one component-config element and one component-profile element.
For example:
...
<components>
<component name="myComponent">
<component-config>
...
</component-config>
<component-profile>
...
</component-profile>
</component>
...
</components>
...
The main properties the developer must be aware of are the following:
In this example the property “Color” has two sub properties; the first one “personalization” defines that the
property will be in the form during personalization. The second one “type” defines the relevant value for this
property.
The portal runtime does not make any assumption concerning the semantic of those sub-properties. The
property attributes are basically used at design time (by administration tools) or during personalization. The
following table describes the property attributes that the developer should be aware of:
Portal Services
Portal Services are declared in service elements inside the services element.
The following XML attributes apply to the service section:
Each component section may contain one service-config element and one service-profile element. For
example
...
<services>
<service name="myService">
<service-config>
...
</service-config>
<service-profile>
...
</service-profile>
</service> ...
</services>
Overview
DataBase server
Web servers
HTTP Request
If the object is not yet available, PRT tries to get it from the local deployment. This step checks the
“revision number” of the application to make sure the local deployment is up-to-date. If a new version
is available in the repository then step 3 is performed. Afterwards, the broker loads the class and
instantiates the object.
When a new version is available, the local deployment is updated. The deployment process gets the
PAR File from the repository and deploys it on the file system. The content of the PAR File is split
into 2 parts. For further details about the directory structure please check: Directory Structure page
88
The Portal Application runs and remains in memory unless a new version is deployed or the
administrator decides to release the application. The system can also discard Portal Application
instances when the Java VM requires freeing some memory.
Application Dependencies
When loading the application, PRT checks the dependencies that are declared in the deployment descriptor
thanks to the “SharingReference” and “PrivateSharingReference” properties. All applications it depends on
are deployed and loaded first.
This step guarantees that the class loader of application it depends on is ready to use. Each portal
application is loaded in its own memory space (cf.: Class Loaders). This space is divided into a public part
corresponding to the API of the application and a private part corresponding to the core implementation.
Hot Deployment
In a cluster scenario (n PRT nodes sharing one repository), the PAR Upload will notify all PRT nodes that a
new version of the application is available. Upon the notification, each PRT node will perform the following
operations:
• Check if the application is already loaded and running.
• Release this application and all elements (components, services, and applications) depending on it.
• Update the local deployment (like describe in step 3).
• Reload the application and the dependents that have been released.
• Restart load-on-startup services
For further detail concerning the PAR Flow please check page 77.
Note: Application can be marked as non-releasable in their deployment descriptor. This flag has no impact
during Hot Deployment; the application will be release in any case. The “non-releasable” property
guarantees that PRT will keep the application instance even when the VM runs low in memory.
Portal
Service API
Request Dispatcher
This is the entry point of the Portal Runtime. In the SAP J2EE environment, it is implemented as a Servlet
running in the WEB Server environment.
The first role of the request dispatcher is to match the URL of the request to a Portal connection and
forwards the request to this Portal Connection.
The Dispatcher can handle all the connections needed. However the Portal Runtime must have a least the
default servlet connection called portal installed and started to work properly.
At startup the role of the request dispatcher is to cover the following functionalities:
• Initializing the Portal Runtime Environment. The Request Dispatcher reads the following
configuration files from the file installation: WEB-INF/conf/dispatcher.properties
• Setup the class loader hierarchy. The different levels of libraries are read from the file installation
and the corresponding class loaders are created in memory. This phase can also be customized
with the following parameters of the prtDefault.properties file:
Dispatcher API
The dispatcher contains a set of API that could be accessed from an external Servlet to communicate with
the dispatcher. Those libraries are packaged into the WEB-INF/lib directory.
Dispatching a Request
When a request comes in, the dispatcher analyses the incoming URL and find the corresponding connection
in order to forward the message. The name of the connection is passed in the URL as follow:
/irj/servlet/prt/<Connection Name>.
The name is used as the key to perform a lookup in the connection bound of the Portal Registry.
Changing the two following files located in the WEB-INF/portal/system/properties can customize some of the
functionality of the Portal Runtime Core.
import javax.naming.Context;
...
The Central Configuration context relies on the JNDI API plus the IStreamSource interface. This interface is
used to read and write the data.
For further information concerning this topic please check: Central Config Storage – How to page 94.
Properties
A first property identifies at which level the cache needs to be placed by adding the CachingLevel property
in your component profile. 3 values are allowed :
• Shared : The cache content is shared among all the users (one java virtual machine)
• User: The content is private for each user
• Session: The content of the component is cached all the time the (servlet) session is running,
whether or not a user is connected. This level is used to cache information related to the browser's
sessions
A second property provides information on the validity of the cache. The property ValidityPeriod will
indicate the validity of the cache in milliseconds.
API
The ICachablePortalComponent interface offers the following methods to control how the PRT cache will
interact with the content of the component.
- hasExpired(IPortalComponentRequest request, long creationTime, long currentTime) returns true it
the cache has expired
- getCachingLevel(IPortalComponentRequest request) returns a CachingLevel object representing
one of the 3 values described above.
A portal administrator could always force the PRT to use the cache properties defined in the Profile of the
component by setting the property ForceProfileCachingParams to true.
Caching Expiration
In general, the cache expiration is controlled by the component either because the validity period expires or
the method hasExpired() returns true. But the Portal Runtime will mark the cached content as expired in the
following circumstances:
- A request or a component event has been sent to the component.
- The node mark has changed on a node.
- The request type is a REFRESH
- An exception is raised when executing the service method that is supposed to be stored in the
cache.
Connection implementations are delivered and packaged as regular Portal Applications. The constraints are
the following:
- The application must be declared “Load-on-startup” in the application config section of the
deployment descriptor.
- The connection must register itself to the Portal Registry
- The connection must implement the IServletConnection interface
Node
When building the POM, the Portal Runtime constructs a tree of special objects called Node. The Node
semantics is defined in the INode interface. It offers methods to:
• Construct and traverse the tree.
• Send and receive events.
• Store and retrieve data
• Access to the Portal Component instance attached to it. Every Portal Component involved in the
process of the request is attached to a Node.
Portal Node
Component
B
Node a Node b
Accessing to a Mode
The default way to render a component in a specific mode is to specify it through the URL used to access
the component.
The Portal Runtime API offers similar mechanisms:
• getComponentContext (NodeMode) on the IPortalComponentRequest.
• setNodeMode(NodeMode) on the INode interface.
• setNodeMode(NodeMode) on the IComponentURI interface using the CreateComponentURI
method.
Mode Handling
When deriving from AbstractPortalComponent, the behavior to handle the mode named xxx is to invoke the
doXxx(IPortalComponentRequest, IPortalComponentResponse) on the Portal Component instance.
Mode Overloading
Portal Component implements their own behavior by overloading the doXxx method as follow:
Mode Delegation
The delegation occurs when a Portal Component decides to forward its rendering to another component.
This mechanism allows developing specialized component. This is done in the configuration of the
component in the portalapp.xml file as shown in the example below:
<component name="mycomp">
<component-config>
<property
name="ClassName"
value="com.sapportals.portal.prt.component.MyComp"/>
<property name="mode" value="edit">
<property name="delegate"
value="DelegateComponent.default"/>
</property>
</component-config>
</component ">
When the delegation for the xxx mode takes place, the doXxx method is called on the delegate component.
In the above example, the Portal Runtime invokes the doEdit method on the component called
DelegateComponent.default. The subsequent request events are also sent to the delegate component until
the mode is set to default.
<application>
<registry>
<entry path="/runtime/prt.modes/admin"
name="adminDelegate"
type="component”
rebind="false"/>
</registry>
...
</application>
System Mode
The Portal Runtime comes with a list of pre-defined modes and delegates.
Portal Hooks
Only internal. CRITICAL TOPIC REQUIRING EXPERT KNOWLEDGE
Purpose
During the request cycle, the Portal Runtime has defined some points that can be customized to add specific
processing. Those entry points are called Hooks.
The Portal Runtime defines 5 types of hooks:
• Document hooks. Concerned by the construction of the output HTML document.
• Component hooks Executed before the service() method of the component. It could add some
content or replace the content.
• Event hooks Executed before firing any event. It could replace the event, forward it to
another object or cancel the publishing.
• POM hooks Executed at every creation of a POM node.
• Response hooks Executed before and after the service() method of the component. The hook
can substitute the original response and is notified when the component has finished to use the
response. The content conversion feature is implemented as response hook
The following picture shows at which of time, the different hooks are called:
Default hooks
Request Event Hook
A portal component can provide a default request event handler. Hence a portal component that doesn’t
provide
Any implementation for a request event (does not overload do<<EventName>> or doRequestEvent) would
let the event handling to the component that provides a default implementation for this event.
The aim is to write the event handling one time and to make it available for all the portal components.
The generic registry tag in the portalapp.xml is a suitable place to declare a default event handler.
Example:
The component named MyEventListener is providing a default implementation for the event named
“myevent”.
<application>
<registry>
<entry path="/runtime/hooks/event/request.listeners/myevent"
name="MyEventListener"
type="component"/>
</registry>
<application-config>
<property name="releasable" value="true"/>
<property name="startup" value="true"/>
</application-config>
<components>
<component name=" MyEventListener">
...
</component>
</components>
</application>
Event Handling
When deriving from com.sapportals.portal.prt.AbstractPortalComponent the following default behavior
applies for the event handling.
Corresponding to the events mentioned above the methods doOnNodeReady, doOnPOMReady,
doBeforeContent, doAfterContent, doOnNodeRemove will be called.
For Request Events there is a special treatment. Given a name xxx of the Event the default implementation
will try to call a method doXxx(IPortalComponentRequest, IPortalRequestEvent). If such a method is not
available doRequestEvent(IPortalComponentRequest, IPortalRequestEvent) will be called.
For Component Events, a similar treatment is executed. Given a name xxx of the Event the default
implementation will try to call a public method doXxx(IPortalComponentRequest, IPortalComponentEvent). If
such a method is not available doComponentEvent (IPortalComponentRequest, IPortalComponentEvent)
will be called.
In addition to that, the filter attached to the listener is invoked before proceeding with normal event handling
and the filter can decide to accept or reject the event handling in the following method:
• boolean accept (IPortalComponentEvent) returns true if the event handling should take place.
The standard JNDI implementation is not able to find classes that are not in the class path. The
implementation that PRT provides simply changes the way the classes are loaded. More precisely, PRT tries
its own mechanism and if it fails, delegates to the standard implementation.
The PRT Implementation is delivered in the JAR File: prtjndisupport.jar. The classes that should be used
to solve class loading issues are the following:
com.sapportals.portal.prt.jndisupport.NamingManager
com.sapportals.portal.prt.jndisupport.DirectoryManager
com.sapportals.portal.prt.jndisupport.InitialContext
com.sapportals.portal.prt.jndisupport.InitialDirContext
Note that only the package name has been changed (not the class name). As a consequence the impact on
the code is minimal since changing the import statement might be sufficient.
import com.sapportals.portal.prt.jndisupport.DirectoryManager;
import com.sapportals.portal.prt.jndisupport.InitialContext;
...
try
{
Context initialContext ;
Hashtable env = new Hashtable();
env.put( Context.INITIAL_CONTEXT_FACTORY,
"com.sapportals.portal.pcd.gl.PcdInitialContextFactory");
initialContext = new InitialContext(env);
Object o = initialContext.lookup(aName);
}
catch ( NamingException e )
{
e.printStackTrace();
}
/PORTAL-INF/properties/jndiprovider.properties
This file is a regular “JNDI Provider resource file” and when loading the portal application, PRT uses it to get
the following JNDI properties:
java.naming.factory.initial
java.naming.factory.object
java.naming.factory.state
java.naming.factory.url.pkgs
Note that properties for object and state factories might provide a colon-separated list of class names. For
more details about these properties, please check the JNDI Tutorial at:
http://java.sun.com/products/jndi/tutorial/beyond/env/overview.html
PRT also expects from that file additional properties defining the schemes that the JNDI Service Provider will
support at runtime:
com.sapportals.portal.prt.jndisupport.scheme
com.sapportals.portal.prt.jndisupport.schemes
#
# Initial Context Factory
#
java.naming.factory.initial=com.sap.tm.application.TravelInitialContextFactory
#
# List of packages where to look for URL Context Factory
#
java.naming.factory.url.pkgs=com.sap.tm.jndi.providers
#
# scheme supported by this JNDI service provider
#
com.sapportals.portal.prt.jndisupport.scheme=tm
#
# State factories
#
java.naming.factory.state=com.sap.tm.application.TravelStateFactory
#
#
# Object factories
#
java.naming.factory.object=com.sap.tm.application.TravelObjectFactory
#
Each factory declared in that file are playing a specific role at runtime. The “Initial Context Factory” will be
the root node to the specific content. The Object Factory will be used to get the raw data from the
persistence layer and load it in memory as Java objects, the state factory will be used to update/store
objects in the persistence layer and the scheme will avoid naming conflicts with other JNDI providers.
JNDI Environment
The environment is a property set (Hashtable) used to specify various preferences and properties that define
the environment for which the contexts are created. This environment typically includes user authentication
information.
Please check the link: http://java.sun.com/products/jndi/tutorial/beyond/env/overview.html
JNDI Context
A JNDI context is an implementation of the javax.naming.Context interface, which provides basic operations
like: bind, lookup and list. It allows to organize data hierarchically.
Approach
The Portal Runtime offers two convenient ways to use the WEB services. The first one consists in offering
Portal services as WEB services. The second one allows portal applications to access external WEB
services.
Portal Services …
The external WEB service is accessed like every other service within the portal. Only the WSDL file of this
external WEB service is requested (even if it is only accessible via Internet). The related tool
Concepts
The principle of the WEB services into the portal is shown below. Very few things are requested to allow a
WEB service to run into the portal. It is as easy as developing a portal service. The whole process (or so) is
hidden to the user. Nevertheless as it interacts a lot with the WSDL files it is useful to know a little how it
works.
For emitter as for receiver, the soap message is not directly handled by the portal service. All is wrapped by
the portal runtime. It can be seen on the schema. The portal service of the requestor is wrapped by the open
tool (ToolKitWebServicePRT) from the WSDL file to the external WEB service. Then, each access to the
soap service is converted by the runtime to a soap message. The answer is waited and when this one
arrives the process can go on. All the manipulations done by the open tool are done before making the PAR
file. There is no intervention of the open tool in the runtime sequence.
On the other side, for the provider, the WSDL file of the soap service within the portal is generated by the
open tool (the same as before). And when a soap message is received, the message is interpreted by the
runtime and redirected to the specified portal service. It is done if the security is respected (rights,
identifications, etc…)
The needed operations are shown more precisely into the architecture part.
D
E
Service Requestor Service Provider
S
Web Services tool
Web Services tool
I
(Open Tools)
(Open Tools) G
Service N
Invocation Service
WSDL WSDL Service
Service SOAP
R
Invocation Consumer SOAP U
Service
N
WSDL SOAP T
Soap Service Service Connection PRT Service I
SOAP Message M
E
Open Tool
Proxy
SOAPProxyP + Connection
Information
Par
Reflection
1. Soap Framework
We provide
• An interpreter for WSDL Language
o to make portal services
o to address external web services
• Serializers / Deserializers generator
o Be able to cope with custom types
• Complex Object wrapper
• Web services configuration stored in the Central Config Storage
1.2 The Portal WEB Services give to developer an easy way to create Web Service.
The portal WEB services implementation is able to receive SOAP Messages. For that, we use the new
libraries inqmysoap.jar, a JAXM 1.0 Implementation (based on the JavaTM API for XML Messaging (JAXM)
version1.0) which was developed as JSR067 under the Java Community Process.
The portal WEB services implementation is also able to deal with the WSDL concept. This implies different
functionalities as SOAP interpreter, Java proxies generation, dynamic service methods invocation….
We provide
• Open simple way to receive SOAP Messages,
o Be listener
o Address Message to the SM
• Interpreter for WSDL Language
o Be able to decode SOAP Message
Address call to the good service
Decode parameter
Construct answer
• Implements JAXR Specifications
o Publish our service to external new calls
Provide WSDL Description of service
Automatic process or not
• Web services configuration stored in the Central Config Storage
2. Soap connection
The SOAP Connection registers itself to the Portal Plug in Framework, to receive request call, extract Soap
messages from it and to pass them to the Soap Consumer
SOAPConnection Class is able to receive HttpRequest. It implements IServletConnection. It gets from the
request, the MimeHeaders and the ServletInputstream, to recreate the incoming Soap message. This class
could be compare to the JAXMServlet class from Sun. The difference is that this approach allows us to
easily include the Soap listening to our Connection Layer.
3. Soap Consumer
The Soap Consumer is in charge of processing the Soap message. That means that it must verify whether
the Soap message is Portal Runtime Compliant. If the XML Soap Message description is well formatted and
if the called service exists on the Portal Runtime environment then the Soap Consumer can work correctly.
The Soap Consumer is also in charge of the answer construction. It calls the Service Manager to access the
called service.
SOAPConsumer class is able to read the Soap Message and its possible attachments in collaboration with
the ServiceManager to retrieve, load dynamically the Portal Runtime Services and address them the call.
For processing a soap message you need to unmarshal it. The Soap message is deserialized to transform it
in a java method call. The xml content is converted to java code. And, on the contrary, when a soap
message is constructed, the Java object is serialized to an xml content (marshal of the soap message). An
xml tag represents a method, another a type, another one the value and so on. This process works also on
interfaces and copes with inheritance (if a class has no deserializer, the parent class is asked for it – and
so for as many levels as needed).
4. Processor
The processor insures the method invocation. A list of processors is maintained by the portal. Now, the only
provided processor is a portal service. Some other processors are in development like the WSRP processor.
5. Registries
Supported types (serialization and deserialization) are maintained by registries. A global one, the Mapping
Registry, contains all the Soap types and some common Java types. Other ones are linked to services. Each
service refers to its Specialized Registry to deals with custom types. These serializers and deserializers are
included into the deployed PAR files.
The specialized registries are loaded in the class loader of the corresponding service.
6. Proxies
7. Security
Soap messages from a SAP Enterprise Portal to our Soap processors may not be encrypted. Other
messages (i.e. outgoing Soap messages) need to be encrypted. There is also be a protection/verification of
incoming Soap messages in order to avoid the execution of our services via Soap attacks. There are two
ways for doing it.
Soap messages are included in HttpRequest. So the normal process of authentication included in the Portal
Runtime environment can do the authentication process. It means the use of https protocol and single sign
on (sso) identification (into the soap header).
The header also contains a way to check the Soap message integrity. Use of the “CRC” principle.
The other way implemented to increase security for soap messages is to block the method call for users who
do not have the permission to use them.
It provide efficient security to the portal WEB services.
SOAP FRAMEWORK
Portal Service
SOAP
Invoked Method
Request
Exception
throws
SOAP
Response
(Fault) SOAP Fault Message
During the invoke of the Web Service’s method if an exception is throw, it is converted automatically in
SOAP Fault Message with the following structure :
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:fault="http://www.w3.org/2001/12/soap-faults">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>%TYPE_ERROR% </faultcode>
<faultstring>%DESCRIPTION_ERROR%</faultstring>
<detail>
<stackTrace >%JAVA_STACKTRACE%</stackTrace>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
When a WebService Portal Proxy Service invoke a webservice method (1), the PRTSOAP Call class in the
PRT SOAP Framework generates the SOAP Request (2) and in the case an where an error will be occur in
the Web Service Server (3) during the SOAP process, normally a SOAP Fault message is generated by the
WebService and returned as response(4). The PRTSOAP Call converts the SOAP Fault message by a
PRTFault Exception (extends SOAPServiceException) (5), and it throws in the WebService Portal Proxy.
9. SOAP Logger
In the PRT SOAP Framework, it exists two forms of log different. All exceptions throws in the SOAP
framework and the Portal Web services are logged in the SOAP Logger, the SOAP Logger file is stored in
the log folder of EP6.0 (the name is soap.log).
The second form of the log is the soap debug information, all soap messages are logged in the SOAP
Logger if it is enable.
By default the information logger is disable, to enable the soap logger to store the soap message and debug
information you must select the property “ Log” in the Configuration menu of SOAP Admin component
Related tools
Some tools are quite useful for developing portal WEB services. The main one is the ToolKitWebServicePRT
(a JBuilder open tool) which contains a WSDL Generator, a serializer and deserializer generator, a proxy
generator and a complex objects wrapper. You may also find interesting the SAPParWizard (for both Eclipse
and JBuilder) for development operations about PAR files.
Within the portal, two other tools can be found, the soap admin tool (for configuration needs) and the Soap
test suite. It contains Interoperability tests (round 1 – to check the compatibility between the portal WEB
services and other implementations). It verifies the compatibility of the round 1 tests with the main soap
platform available on the market (systinet, .net, mssoap, apache…). It contains an example of external WEB
service use (Google WEB service, allows searches on Google) and an example of client proxy use (This
proxy is open tool generated). It also contains an example which shows a way of using the WSDL generator
(on the fly WSDL file reading and writing).
Approach
The following picture shows the Portal Application development model:
A Portal application has to be packaged in a Portal Archive (PAR) file and must be uploaded in the Portal
before being executed.
PAR Export
Upload
Import
PAR
Execute
and Test
The goal of the PAR IDE is allow a Portal Application developer to cover all the development steps in one
environment:
• Export/Import/Create PAR files.
• Edit, code, compile and add resources to Portal Application.
• Upload/Execute/Debug Portal Application.
Additional Feature
The PAR IDE offers also an API to register a plug-in that can be called during the creation of the PAR File. It
allows Portal Application developers to extend the original Portal Application development model.
This add-on is also an eclipse plugin and must follow few simple rules:
1. It must be loaded at the eclipse startup...
2. …in order to register to the PAR plugin.
3. It must implement two interfaces, one for the packing the other for the unpacking.
1. Eclipse startup
The plugin add-on has to be loaded when eclipse starts. It will allow this add-on to register into the PAR
plugin. In order to achieve this follow the instructions.
<extension
point="org.eclipse.ui.startup">
</extension>
In the base class of the add-on plugin (the first class called when the add-on plugin is started, and where
org.eclipse.ui.plugin.AbstractUIPlugin is extended) the interface
org.eclipse.ui.Istartup with its unique method (earlyStartup()) must be
implemented.
2. Register
Now, it can be assumed that the add-on plugin is loaded at startup. So in its constructor, it can register itself
to the PAR plugin. Call of the static method of
com.sap.portal.developmentTools.ideSpecific.eclipse.PortalPlugin class:
registerPlugin(String pluginId, IParIdePlugin aPlugin). The plugin id must be
unique.
The add-on plugin has to clearly specify the final state of the operation using the method
setFinalState(int status) from the class
EP50 Archives
EP50 PAR Files and ZAR Files were using a different format and the XML based deployment descriptor as it
is today was missing. When EP50 archives are uploaded to the portal the EP60 Deployment descriptor is
dynamically generated and stored in the repository. It is important to know that those generated deployment
descriptors will by default enable the EP50 Deployment and Class Loading Policy.
UNIX/Windows compatibility
As the PRT is written in Java, and proposes a development model relying on the Java Technology, a Portal
Application is portable from Windows to Unix.
However, a common portability problem often encountered by Portal Application developers when running
on Unix an application developed on Windows is the case-sensitive issue.
If a file name or a WEB resources is wrongly capitalized, the error will occur only in Unix and will be hidden
in Windows.
In order to help Portal Application developers to identify those kind of problems on the Windows platform,
PRT offers a case-sensitive check when accessing WEB resources via the Portal Component API.
This check produces a warning message each time that the name of the resource in the file system is not
the same than the name passed as parameter of the API regarding its capitalization. The warning message
is logged in a new file called diagnostic.log. With this mechanism, Portal Application developers can fix their
applications on Windows without having to wait to see their applications crashing on Unix.
To enable this check, the PRT should run on Windows and in development mode by setting the
portal.runtime.permission.mode property to development
Notification Service
Application name: com.sap.portal.runtime.system.notification
The notification Service is responsible to provide a support for communication between PRT instances
running in different Portal Environments. The notification service has two goals:
• Deliver an API to send and receive messages between different WEB servers. The API is built
around the following objects:
o INotificationService. The service use to subscribe and receive message
o ITopicListener. Interface implemented by objects that want to listen for messages
associated to a certain topic.
o TopicDataContainer Representation of the message sent from a PRT to another PRT.
• Maintain the cluster information. The Notification Service implementation must understand the
cluster configuration. This is the only service having such knowledge of the execution infrastructure.
This implies that a version of the Notification Service should exist for every supported platform. In
the SAP J2EE environment, the Notification Service uses the PRT Bridge to manage the
communication between the different nodes of the cluster. The PRT Bridge uses the SAP J2EE
cluster configuration to obtain this knowledge.
The following figure illustrates the architecture of the Notification Service.
In this example, the component B on PRT2 is registering to a specific topic and the component A is
publishing a message associated to the topic in which the component B is interested in. When the
component A publishes on PRT1, the message is sent to all the PRTs declared in the cluster.
PRT 1 PRT 2
Component A Component B
defined on IPortalComponentResponse. Everything written from this point on is treated as belonging to the
content type set. With this mechanism a component can even generate multiple content types during one
content generation. The Content Conversion Service will convert them all to the target type which is the type
of the PortalResponse.
Content Converters
To perform the conversion the service uses content converters. A content converter is capable of converting
content of one content type to another. It implements the interface IContentConverter that defines the
method:
Using the parameter request, the converter has access to the components resources and can locate any
scripts/parameters that the component might provide to perform the conversion.
Content converters are provided to the PRT by content converter factories that implement
IContentConverterFactory. This interface contains the method:
The factory must be registered in the Portal Registry. The path in the registry where the factories must be
registered can be obtained by calling getContentConverterRegistryRoot() defined on
IContentConversionService.
IContentConversionService contentConversion =
(IContentConversionService)mm_serviceContext.getService(IContentConversionService.KEY);
String mm_rootKey = contentConversion.getContentConverterRegistryRoot();
String fromType = URLEncoder.encode(PortalComponentContentType.RSS.toString());
String toType = URLEncoder.encode(PortalComponentContentType.HTML.toString());
String mm_RSSToHTMLConverterRegistryString = fromType + toType;
PortalRegistry.getInstance().bind(mm_rootKey + "/" + mm_RSSToHTMLConverterRegistryString,
myFactory);
a
a
c
a b
c
b b
Portal Runtime
R/3 R/3
System 1 System 2
f
a If the user logs off from the Portal, all JCO connections requested in this session will be closed.
b If the HTTP session timeout occurs, all JCO connections requested in this session will be closed
c If a connection limit (configurable) is defined in the JCO Client Service for a specific destination,
this limit is maintained for each user over several sessions. If for example, each user is allowed to
use 10 connections to R/3 System 1 in the scenario above, than the service ensures that this limit
does not exceed the sum of connections in both sessions used by User 1.
Connections are pooled. The JCO Client Service maintains a timeout for connections contained
d
in each pool. This can be configured per destination.
Connections that are no more referenced in Portal Applications are identified by the VM garbage
e
collector and deducted from the connection limit.
f All function modules accessed by a specific user are traced (configurable). This is used to
generate the user definition in R/3 with the appropriate authorizations to execute a specific
business package.
Related documentation:
• JCO Client Service API documentation.
• JCO Client Service Tutorial. Available in iViewStudio and PRT documentation.
• Technical Article: How to share JCO connections in iViews. Available in iViewStudio.
Service Description
• Portal services that want to be called via RFC must implement a new interface
com.sapportals.portal.prt.service.rfc.IPRTRFCListener.
• Portal Service should then register in their afterInit() method the RFC it want to cover using
the following function of the RFC Engine Service.
setFunctionCallListener(String nameOfFunction, String nameOfService)
<application alias="TestRFC">
<application-config>
<property name="ServicesReference" value="RFCEngine"/>
<property name="releasable" value="true"/>
</application-config>
• Finally, the Portal Service must implement the function handleRequest to receive calls from
R/3 system.
if (function.getName().equals("STFC_CONNECTION"))
{
output.setValue(input.getString("REQUTEXT"),"ECHOTEXT");
output.setValue("This is a response from the TestRFCService
side!","RESPTEXT");
}
return function;
Important Points
• The plugin name should be the name of the PAR file (this is a good way to guarantee its
uniqueness).
• The names of the directory must match properly under meta and data!
• From a configuration perspective, the plugin name, more precisely the directory in which the
configuration is stored (meta as well as data, in this case: com.sap.portal.prt.config.prototype)
is called the Root-Plugin. This is import for ConfigRootFolder considerations (this will be
detailed later).
ca.name=com.sap.portal.prt.config.prototype
ca.version=6.0.1.1
cma.name=com.sap.portal.prt.config.prototype.hello
cma.version=6.0.1.1
cma.storage=pcd
ca.dependencies CA-Dependencies No
cma.dependencies CMA-Dependencies No
Modify portalapp.xml
The configuration of an application can be administered via the general Configuration UI or via the
config mode of the portal application. Configuration data for a service, can be administered by using a
virtual configuration component
To access the Config Framework APIs, the Portal Application needs to specify a Private Sharing
Reference in portalapp.xml:
<application-config>
<property name="PrivateSharingReference
value="com.sap.portal.runtime.config"/>
</application-config>
Note that although the Config mode will use the Config FWK component to display the configuration,
the application itself does not need a direct dependency on the Config Component. It just need the
dependency on the Configuration Framework service in order to access the APIs.
A Portal Component can also specify a property called the ConfigRootFolder. This represents the
path within the overall configuration structure of your component specific configuration. If no
ConfigRootFolder info has been specified, the Config Component will take the name of the application
as a default (the name of the PAR file).
<component name="HelloWorld">
<component-config>
<property name="ClassName"
value="com.sap.portal.prt.config.HelloWorld"/>
</component-config>
<component-profile>
<property name="ConfigRootFolder"
value="/com.sap.portal.prt.config.prototype"/>
</component-profile>
</component>
Virtual Components
Portal Service configuration are managed by creating virtual Portal Component while giving it a right
ConfigRootFolder.
The virtual Portal Component will use the delegate Component to the config mode. This is done by
adding the following lines in the portalapp.xml:
<application-config>
<property name="PrivateSharingReference"
value="com.sap.portal.runtime.config,
com.sap.portal.runtime.system.hooks"/>
</application-config>
Then the virtual Portal Component is created as an instance of the Config Component.
<component name="FontConfiguration">
<component-config>
<property name="ClassName"
value="com.sapportals.portal.prt.component.ConfigComponent"/>
</component-config>
<component-profile>
<property name="ConfigRootFolder"
value="/com.sap.portal.runtime.config.prototype/font"/>
</component-profile>
</component>
This will uniquely identify the listener’s application throughout all the applications. It is a good pattern
to use a combination of the application name and the component name. In this case we have
com.sap.portal.prt.config.prototype as the application name and HelloWorld which is the
component name . Of course if within a application there is a need for only ONE Config listener,the
application can just use its name.
• public void configEvent(ConfigEvent event): is called when an action occurred on the specified
Configuration
try {
// get Configuration Service
IConfigurationService configurationService = Configuration.getInstance();
IConfigEventService eventService =
configurationService.getConfigEventServiceInstance();
Elements of domains can be plugins, configurables or config items generally speaking. Application registers the
listener in the method init(IPortalComponentInitContext context) of the Portal Component.
Remove listener
When the application is released, it has to remove any listeners of the IConfigEventService.
try {
// get Configuration Service
IConfigurationService configurationService = Configuration.getInstance();
IConfigEventService eventService =
configurationService.getConfigEventServiceInstance();
// remove listener
eventService.removeConfigEventListener(this);
}
catch (InvalidEntryException e) {
e.printStackTrace();
}
catch (InitialConfigException e) {
e.printStackTrace();
}
Page 72 /113
14 Exception Handling
This chapter gives general rules and guidelines to manage exception in the Portal Applications. This chapter
also describes a framework implemented by the Portal Platform to enrich the information associated to
exceptions.
Issue Overview
Exception handling influences the quality of Java programs because:
• It ensures that the program can continue in error conditions.
• It allows the user to find the problem which caused a thread to terminate. An exception that caused
the termination of a Portal Application should lead to the causing problem by giving a meaningful
information.
Coding Rules
Page 73 /113
Do not have empty exception handlers
Page 74 /113
Adding Extra Information
The Portal Platform allows a developer to add extra information to exceptions thrown by Portal Applications, by
proposing an Exception catalog and a tool to display this information to the users. The goal of this approach is to
help Portal administrators to diagnostic in a very fast and effective way problems occurring in the Portal
Platform.
Log Viewer
The PRT provides a tool called LogViewer used to analyze Portal Platform Log files in order to facilitate the
diagnostic of errors and problems occurring in the Portal Platform.
The LogViewer offers 4 main functionalities
• browse a file system to locate log files.
• View and download log files to a local system.
• Search for specific patterns in a log file or a list of log files present in a directory.
• Analysis error and exception logged in a specific files.
The functionality that analyzes errors and exceptions is a mechanism based on a Exception Catalog made of a
set of Exception files containing:
• additional info for the exception.
• filter information to retrieve the most relevant information out of the Java stack trace.
Exception Files
Exception Files are test files containing the following key word:
Key word Description
stacktrace Give the exclusion filter used to parse the stack trace. After an exception, you only need
to know the relevant stack trace line. For the portal, the java exceptions are not always
relevant.
You then specify that you want to exclude them (stacktrace:java,javax) and the first
stack trace line starting with anything else than "java" or "javax" will be selected and
displayed in the result.
message For this specific error you may want to display a particular message. Just put it there.
For example: "message: This is the specific message for this exception."
action You can also add an advise referring to this exception. This is the purpose of this key
word. For example: "action: Please contact you system administrator."
Page 75 /113
Example:
The com.sap.portal.testException can be described in the Exception catalog in a file called:
com.sap.portal.testException.err containing the following information:
stacktrace:
Message: A test Exception occurs.
Action: Check that the test configuration has been set up correctly in the test
directory
In that case, as there are no information after “stacktrace”, the keyword can be omitted. It means that the first
line of the stack trace will be selected as the correct one (indicating the file, the method and the line where the
error occurred). The initial error and message will also be displayed. And of course the message and action will
appear.
All these values will be displayed by the help window of the LogViewer.
Example:
The Portal Applicaion CustomerInfo PortalApplication sends an exception named
com.sap.portal.customer.InvalidCustIDException. In that case, the associated Exception file
com.sap.portal.customer.InvalidCustIDException.err will use the stacktrace keyword to filter out from the
stacktrace analysis any references to the CustomerInfo application
stacktrace:com.sap.portal.customer.CustomerInfo
Message: Customer ID is not valid
Action: Check your application to verify that the customer ID has a valid format.
In that case, the help window of the LogViewer will clearly extract from the stack trace the file, the class name,
the method name and the line of the caller of the CustomerInfo application that should be corrected.
That means that the first stack trace line which does not start with “com.sap.portal.customer.CustomerInfo” will
be kept and parsed (to display the file, the method and the line where the error occurred). And the message
and action information will also appear in the display window.
In that case, only the relevant information is shown. The error occurs in the “CutomerInfo” class but it is the call
of that class which is not correct. So only the caller should be displayed. It is what the LogViewer is doing.
Exception Catalog
The exception catalog is located in the private errors folder of the LogViewer Portal Application. It contains a
pre-defined list of exception files either sent by the Portal or representing the standard Java Exception.
For the next version of the PRT (SP2), the catalog will be moved to the Application Repository and Portal
Applications will be allowed to enrich the catalog during PAR uploading.
A new deployment hook will be developed and will store in the PCD, every Exception Files defined in the private
errors folder of Portal Applications
Example:
PORTAL-INF/errors/com.sap.portal.testException.err
Page 76 /113
15 Appendix
PAR Flow
This chapter describes the PAR Flow and explains how PAR Files are deployed to make the corresponding
portal application available on all PRT nodes of a SAPJ2EE cluster.
The Portal Administrator typically uses the “Archive Uploader” component to upload and deploy a Portal
Applications to the portal. He or she can also import content to the portal using some external tools that are
provided by the persistence layer.
This step will update the “local deployment” of the portal application on each server. The update of the local
deployment requires Hot Deployment capabilities, this is why all portal applications are releasable.
Each PRT node proceeds as described below:
• It checks if the application is already loaded and drops the corresponding instance. That step also
checks and drops all entities (applications, components and services) that are depending on the current
application.
• It starts the deployment process. This process gets the PAR File from the repository and updates the
local deployment by expanding the archive content.
• It then restarts all portal applications that have been dropped.
The main purpose of the local deployment is to improve performance at runtime by providing a fast access to
classes and to portal application resources. The local deployment avoids additional round trip to the application
repository and in that sense must be considered as a cache for portal applications.
Page 77 /113
The check is done by comparing a “revision number” (updated during the PAR Upload). If the revision number of
the local deployment differs from the repository then the local deployment is updated before loading the
application.
Deployment Policy
The local deployment is done taking care of the “DeploymentPolicy” property declared in the deployment
descriptor.
- If this property is set to “5.0” then the deployment is backward compatible with the EP50 version of the
portal. In that case the old folder is not removed and the deployment process simply overrides the folder
with the new content.
- If the deploymentPolicy property is missing, a regular deployment is done; the old deployment folder is
removed and then replaced by the new one. It is important to understand that the EP60 deployment logic
assumes that the application doesn’t store any configuration locally; everything should be store in the
repository.
Page 78 /113
Deployment Hook
The Portal Runtime has implemented a hook called deployment to allow custom code to be executed at some
pre-defined points of the deployment process.
A deployment hook is a service delivered in a Portal Application that binds some name in the portal registry
deployment folder.
<application>
<registry>
<entry path="/runtime/deployment/com.myPackage.myDeploymentHook"
name="myDeploymentHook"
type="service”
</registry>
<services>
<service name="myDeploymentHook">
...
</service>
</ services >
</application>
This service implements the IDeploymentHook interface defining the following method:
• IDeploymentHandler createHandler(IDeploymentEvent) returns a deployment handler depending on the
deployment event set by the Portal Runtime. The PRT defines two kinds of deployment event.
1. DeploymentEventType.BEGIN_UPLOAD
The PAR has been loaded in the portal repository. The handler can execute custom code on each
entry of the PAR.
2. DeploymentEventType.BEGIN_DEPLOYMENT.
The PAR is about to be deployed in the Portal Environment. The handler can execute custom code
on each entry of the PAR.
A IDeploymentHandler instance returned by the deployment hook has then the chance to implement specific
code in the following method:
• boolean handleEvent(IDeploymentEvent) The deployment event passed as parameter gives access to
the PAR currently loaded. The boolean value returned by the handler will condition the execution of the
normal deployment/upload process. If the value is true, the normal behavior is not executed. If the value
is false, the rest of the process is executed.
Page 79 /113
Text localization and Portal Components internationalization
This section examines issues involved in designing and developing portal applications that support multi
language environment.
API
The Portal Runtime API offers two methods defined in the PortalComponentRequest to make the Portal
Application aware of localization aspects.
• java.util.Locale getLocale() Return the locale object associated with a Portal
Component. The value returned is determined at runtime depending on multiple parameters described later
on.
• java.util.ResourceBundle getResourceBundle() Return the Resource Bundle associated with a Portal
Component. The Resource Bundle returned by this method depends on the Locale of the application and on
the resource bundle name defined in the Portal Application profile.
Page 80 /113
Locale lookup
The locale lookup rule implemented by the Portal Runtime follows the order described below:
1. Component locale. The locale of the component is specified by the following two properties and allows
forcing a component to use one specific local. This could be used for administration components.
a. ForcedRequestLanguage
b. ForcedRequestCountry
2. Portal Mandatory locale. This is defined in the prtDefault.properties and forces a Portal installation to
use one and only one local. Administrators to setup a portal environment use this locale.
a. request.mandatorylanguage
b. request.mandatorycountry
3. User locale . This is the local attached in the user’s profile logged in the system.
4. Request locale. The Request locale is defined by the browser. This is used for example for anonymous
user or users without locale defined in their profiles.
5. Portal Default locale. This locale is defined in the prtDefault.properties by the following two properties:
a. request.defaultlanguage
b. request.defaultcountry
6. System Default locale. The Java default locale defined by the system. (Either the operating system, or
the Java virtual machine)
<Portal Archive>
|
+-- META-INF
+-- MANIFEST.MF
+-- …
+-- PORTAL-INF
| |
| +-- private
| | +-- classes
| | +-- my_Bundle.properties
| | +-- my_Bundle_fr.properties
Page 81 /113
Portal Component Java Code
The following is a code example showing how to access to a resource bundle from a Portal Component Java
code. In this example, the corresponding PAR must contain one resource bundle per supported language.
import com.sapportals.portal.prt.component.*;
import com.sapportals.portal.prt.resource.*;
import java.util.ResourceBundle;
Request/Response handling
When a data is sent from the browser to the Portal Component for processing, the data is converted by the
Portal Runtime according to the following properties defined in the Portal Configuration file
The data are read in a Unicode format and are then manipulated accordingly. The locale of the browser can be
found by the getLocale() method of the original servlet request.
If the property runtime.doubleByteSupport is set to false, the encoding used by the Portal Runtime is the
encoding defined at the servlet container level.
The runtime.doubleByteSupport.encoding property is also used to encode the data sent by the Portal
Component and presented to the user in the browser.
JSP Support
When a portal application uses a JSP resource containing double byte characters, the Portal Runtime needs to
understand the character set that has been used to create the file. Thus the Portal Runtime can parse the file in
the correct encoding and generates the corresponding Portal Component in UTF-8 encoding encoding (or in any
encoding specified in the runtime.doubleByteSupport.encoding property).
This is done by specifying the encoding in which the page has been saved in the pageEnconding directive of the
JSP file as shown in the following example:
<html>
<%@page pageEncoding=”shift_JIS” %>
…
Page 82 /113
Permission model for Portal Components and Portal WEB Services
This chapter explains the model implemented in the Portal Runtime to control Permission on Components.
The goal of this feature is to control the access to the following Portal Objects.
• Portal Components started using the prtroot URL.
• Portal Services accessed as WEB Services by the soap connection.
• Safety Level : A security level in a zone. It allows to group objects belonging to a zone into different
categories.
Examples:
Security Zone
The security zone provides during the development phase, a way to abstract the security level that a portal
component or a Portal Service will require at runtime.
Technically the zone is a string defined in the portal application descriptor. From a PRT perspective there is no
restriction, any string could represent a security zone. But form an administration perspective it is necessary to
normalize the way portal component use this concept.
The Portal application developer doesn’t have to any knowledge of the name of the roles or of the name of the
users that will be present in the Portal environment in which the Portal Application will be installed.
The zone defines a logical catalog containing a set of Portal Objects.
The administrator of the Portal Environment has to associate the principal of the system to the zones by creating
ACLs defining the permission needed to access to a specific zone.
Page 83 /113
Safety level
Within a zone, developers can define different safety levels. Each of these safety levels can then be assigned to
different permissions by the administrators of the system. This mechanism helps Portal administrators to
organize and classify objects belonging to a zone.
The PRT doesn’t make any assumptions on the value representing a safety level. It could be any String. The
Portal Runtime recommendation is to use the following values:
Implementation
During the load of the Portal Application archive in the system, the zones are created if they do not exist. Entries
corresponding to the Portal Objects are then created into the zone.
When accessing a Portal Object (Portal Component or Portal Service), the Portal Runtime checks if the current
user has the permissions required to access to the zone the Portal Object belongs to. This zone is defined in the
Portal Application descriptor by the property SecurityZone. The check is performed by the application
repository by testing if the current user has execute permission for that “security zone”. If the user has not
enough permissions, a security exception will be returned by the Portal Runtime.
<component-config>
…
<property name="SecurityZone" value="com.sap.portal/high_safety"/>
…
</component-config>
Example of portalpp.xml containing the definition of a zone for a Portal WEB Service.
<services>
….
<service-config>
….
<property name="SecurityZone" value="com.sap.test.TestBO/medium_safety">
</property>
<property name="WebEnable" value="true"> </property>
<property name="WSDL" value="TestBO.wsdl"> </property>
</service-config>
..
Page 84 /113
Recommendations
The naming convention for the security zones is the following:
{Namespace of business application}/{safety level}/{portal application (optional)}
The third part of the name, the portal application name, is optional. It is the full name of the application the
security zone is defined for. This allows the administrator to configure the permissions for one portal application
separately. In most cases, this is not necessary and only increases complexity.
Page 85 /113
Portal Object Name and Alias
The goal of this chapter is to focus on how to identify and access to the objects manipulated by the Portal
Runtime. Each of the Portal Objects are accessed on different occasions summarized by the following table:
Name
The following rules apply for naming objects in the Portal Runtime.
The ApplicationName is defined by the name of the file containing the application.
The ServiceName or the ComponentName is defined by prefixing the name of the component or a service
defined in the portal application descriptor with the name of the application
<ApplicationName >.<name>
Alias
The Portal Runtime offers also a concept of alias that allows for compatibility reason to define alternate name for
Portal objects. The following rule apply to declare an alias on Portal objects.
• Application can have alias, then the alias can replace without any limitation the name of the application.
For example, <ApplicationName> == <ApplicationAlias>
• Component can have alias by using the alias of the application. For example
<ApplicationName>.<name> == <ApplicationAlias>.<name>,
• Service can have an alias. In that case, the name of the service can be replaced by the service alias. For
example, <ApplicationName>.<name> == <ServiceAlias>. In the case of a Service, using the alias of
the application name is not accepted. For example <ApplicationAlias>.<name> is not a valid service
name.
Page 86 /113
Example
If the myApplication.par defines the following entries:
<application alias="myAlias">
<services>
<service name="myService" alias="alias.service" >
...
<components>
<component name="myComponent" >
Page 87 /113
Directory structure
This section describes the directory structure after deployment. That should help the developer to understand
what are the resources necessary at runtime and how portal applications are deployed locally.
<SAP J2EE>\<server>\services\servlet_jsp\work\jspTemp
|
+-- irj
|
+-- portalapps <== WEB resources
| |
| +-- <myApplication> <== a subfolder for each portal application
| |
| +-- images
| +-- scripts
| +-- ...
|
+-- WEB-INF
| |
| +-- lib
| +-- portal
| | |
| | +-- logs
| | +-- lib
| | |
| | +-- system
| | | +-- lib
| | |
| | +-- portalapps <== Non-WEB resources
| | |
| | +-- < myApplication > <== a subfolder for each portal application
| | |
| | +-- classes <== API: java classes only
| | +-- lib <== API: jar files only
| | |
| | +-- private <== Implementation of the portal application
| | | +-- classes <== CORE: java classes only
| | | +-- lib <== CORE: jar files only
| | |
| | +-- portalapp.xml <== deployment descriptor
| | |
| | +-- META-INF <== deployment descriptor
| | +-- MANIFEST.MF <== Manifest file
| |
| |
| +-- deployment
Page 88 /113
- The private part (ie: the PORTAL-INF folder) is deployed in a secure folder which is not accessible
from the browser (ie: under WEB-INF). The private part basically contains the code (API and CORE
implementation), the deployment descriptor and some application-specific files.
Note: The local deployment is a copy of the original PAR file content stored in the application repository. It is
important to understand that the local deployment is a kind of cache. That means for instance that a change
made in the deployment descriptor deployed locally might have no impact at runtime since PRT night use the
original version instead.
Portal Application
Web Resources non-web resources
Shared code
(APIs)
Referencing
Portal
access to config, use Applications
application data,
personalization,
etc..
//
From an execution perspective, a Portal Application is a collection element of the two currently supported types,
Portal Component and Portal Service that have a use relation between each other.
Page 89 /113
Application X
alias=Y
R
Service a
alias="p"
Application R Application
Service b
Access by
getService(name) ... Application
provides service
instances Portal Component u
Dependencies by
SharingReference (incl.
Portal Component v ServicesReference) or
PrivateSharingReference
enable visibility of type
... definitions
non-default
API
only if
"CoreAccessInAPI"
policy in use Core
Page 90 /113
A B C
SharingReference: B PrivateSharingReference: C
SharingReference: C
Page 91 /113
Deployment Descriptor example
This is a deployment descriptor (portalapp.xml file) example of an application that contains one Portal Service
and one Portal Component. The Portal Service has one property in its profile and the Portal Component has two
properties.
<application>
<application-config>
<property name="releasable" value="true"/>
</application-config>
<components>
<component name="ChatRoom">
<component-config>
<property
name="ClassName"
value="com.sap.portal.exampleapp.impl.ChatRoom"/>
</component-config>
<component-profile>
<property name="AuthRequirement" value="user">
<property name="personalization" value="none"/>
</property>
<property name="diplayHistory" value="10">
<property name="plainDescription" value="Number of messages"/>
<property name="personalization" value="dialog"/>
</property>
<property name="diplayStyle" value="list">
<property name="type" value="select[list,history]"/>
<property name="personalization" value="dialog"/>
</property>
</component-profile>
</component>
</components>
<services>
<service name="ChatService">
<service-config>
<property name="startup" value="true"/>
<property
name="className"
value="com.sap.portal.exampleapp.impl.ChatService"/>
</service-config>
<service-profile>
<property name="chatHistory" value="100"/>
</service-profile>
</service>
</services>
</application>
Page 92 /113
Application Example
Matching the deployment descriptor above, we have the following PAR File content:
hello.jpg
META-INF/MANIFEST.MF
PORTAL-INF/portalapp.xml
PORTAL-INF/lib/chatapi.jar
PORTAL-INF/private/lib/chatimpl.jar
META-INF/MANIFEST.MF
com/sap/portal/exampleapp/api/IChatService.class
and chatcore.jar:
META-INF/MANIFEST.MF
com/sap/portal/exampleapp/impl/ChatService.class
com/sap/portal/exampleapp/impl/ChatRoom.class
Page 93 /113
Central Configuration Storage – How to
The Central Configuration Context is a JNDI context, which can be, used to read/write any kind of data to the
repository. This feature can be used by any portal application to store additional configuration files or resources
that are to be shared by all PRT nodes on the cluster.
A sub context dedicated to the application exists by default. Components and services can access to the context
of the application the belongs to by calling the lookup method on the root context.
import javax.naming.Context;
...
The Central Configuration context relies on the JNDI API plus the IStreamSource interface. This interface is
used to read and write the data.
import javax.naming.Context;
...
As a contrary, the application might want to organize it’s data using its own logic. It can creates its own
hierarchy thanks to the Context.createSubcontext method.
try
{
context.createSubcontext("/"+appName+"/"+contextName);
}
catch (NamingException e)
{
...
}
How to store and retrieve config files to/from the central location?
The application can store and retrieve any kind of data as soon as it can provide an implementation of the
IStreamSource interface. That interface is simply used to get an input stream to the data source.
Page 94 /113
Storing a config file
To store a config file, the application typically uses the bind or the rebind. The StreamSource helper class can
be use by the portal application. It implements the IStreamSource interface and as constructors for common
data source (Files, java.util.properties, …).
java.util.Properties properties = …
javax.naming.Context context = …
String myConfig = “/MyAppName/data.properties”;
try
{
StreamSource source = new StreamSource(properties);
context.rebind(myConfig, source);
}
catch (NamingException e)
{
...
}
Retrieving a config file: The application has to use the lookup method to get back an IStreamSource to its
config file.
javax.naming.Context context = …
String myConfig = “/MyAppName/data.properties”;
IStreamSource source=null ;
try
{
source = (IStreamSource)centralConfigContext.lookup(myConfig);
}
catch ( NamingException e )
{
source=null ;
}
try
{
IStreamSource source = …
java.io.InputStream is = source.getInputStream();
java.util.Properties properties = new Properties();
properties.load(is);
is.close(); //important
}
catch (IOException e)
{
ILogger logger = PortalRuntime.getLogger();
if (logger!=null && logger.isActive()==true)
logger.severe(e, "Operation failed");
}
Page 95 /113
SAP J2EE integration and interaction
The Portal Runtime supports two types of interaction with object defined and executed in the SAP J2EE
environment.
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpServlet;
2. The PAR file should declared the Servlet object as a component of type servlet.
<components>
<component name="ServletTest" >
<component-config>
<property name="ClassName" value="com.sapportals.portal.prt.component.ServletTest"/>
<property name="ComponentType" value="servlet"/>
</component-config>
</component>
<Portal Archive>
|
+-- META-INF
+-- MANIFEST.MF
+-- …
+-- PORTAL-INF
| |
| +-- private
| | +-- lib
| | +-- servletTest.jar
Under construction
Page 96 /113
Portal Content Abstraction
The Portal Content Abstraction is an API that provides to PRT the ability to start and render any kind of “portal
objects”. The simplest portal object that can be started is of course the portal component, but PRT doesn’t make
any assumption on the object type and PRT knows nothing about the source of the object and about its
implementation.
The benefit of this content abstraction is quite clear. PRT does not depend at all on the structure of the content
itself. The concept of Roles, Worksets, iViews, Pages, Templates or whatever has no impact on the portal
runtime.
JNDI Basis
The API used to achieve this abstraction is based on the JNDI API. This approach assures to benefit from JNDI
defined operations and to adhere to this existing standard. This allows to keep the API thin. All metadata
regarding authentication (and more) are passed using standard JNDI properties.
For further detail concerning JNDI Providers please have a look to: PRTJndiSupport page 42.
Object o = null ;
try {
o = initialContext.lookup(prtroot);
}
catch ( Exception e ) { }
As shown in the code above, PRT checks if the object implements the IPropertyContentProvider interface. That
interface is the entry point providing all information that PRT needs to find the portal archive, the portal
application and finally the implementation class that will be responsible of the rendering.
Page 97 /113
Portal Runtime Help Mode
The objective of this chapter is to describe how the default Help Mode is implemented in the PRT.
The Help mode allows a content developer to ship help texts in a PAR and to render a Portal Component in the
help mode by displaying this help text.
The Portal Runtime supports 4 kinds of help text sources:
• Help Text is stored in the PAR file of the component that is rendered in help mode. The structure is
totally free and should only respect the public/private rules of the PAR file structure.
• Help Text is stored in the PAR file according to a pre-defined structure that supports localization of the
texts. The help texts must be stored in the public folder named help. When retrieving the text files, the
Portal Runtime will except this text file to be located in a subfolder corresponding to the language of the
user.
• Help text is accessed with an external URL. In that case, the help can be displayed in a separate frame.
This behavior is defined by another property of the Portal Component called HelpIsolationMode.
• Help text is retrieved from another Portal Application. It allows the packaging of the help texts in
different PARs. This approach does not support text localization.
Page 98 /113
The Portal Runtime will look first to the HelpName property and then will inspect the value of the HelpURL
property. If none of those properties is set, an error message is displayed.
The two following tables show examples of different values of those two properties.
Example Description
http://www.yahoo.com Connect to the specified URL to get help for the Portal
Component. This is the case when the help texts are
stored in an external web site.
In that case, the Portal Component can decide to
display the content of this external web site in a
separate frame. To use this feature, the Portal
Component should set the value of the property
HelpIsolationMode to URL.
docs/index.html Access to the file named index.html in the docs
directory of the Portal Application. This is the typical
scenario where the help text is shipped in the PAR of
the Portal Component. This format is absolutely free
and does not support text localization.
/com.sap.portal.helpcomponent.default/docs/index.html Access to the files named index.html in the docs
directory of the helpcomponent Portal Application. In
that case, the help text is shipped in a separate PAR.
Example Description
Index.html Access to the file index.html located in the following directory:
help/{user_language}/index.html
where {user_language} is the language of the user accessing the
component .
if a language specific version is not found, it uses the top level file
without any language code.
Page 99 /113
Portal Runtime Test Mode
The objective of this chapter is to describe how the Test Mode is implemented in the PRT.
Rendering a Portal Component in test mode will perform the following operations:
• Checks if the Portal Component provides support for this mode.
• Invokes every test methods defined in the Portal Component.
• Format the output of the test to HTML or XML format.
A Portal Component provides support for the test mode by implementing the ITestable interface defined in the
PRT API.
Each test methods invoked by the Test Mode execution, are written against the following pattern:
The Portal Component is invoked in test mode by using the following URL:
• /irj/servlet/prt/portal/prtroot/<MyComponent>/prtmode/testComponents/testRendering/html
<Portal Archive>
|
+-- META-INF
+-- MANIFEST.MF
+-- …
+-- PORTAL-INF
| |
| +-- portalapp.xml
| | +-- logger
| | +-- logger.xml
The logger configuration file gives a list of Portal Runtime loggers. Every loggers of this list are following an
implementation a model proposing two views on the loggers.
• Application Developer view. A logger is defined by its name, a Java interface, a string formatting
pattern, the default activation flag and a logging level. One a logger has been defined it is accessed
through the Portal Runtime API:
o getLogger(String) on the Portal Component Request.
o getLogger(String) on the Service Context.
By default those methods return an ILogger object. However, the Portal Runtime offers a way to
define and return another interface.
• Administrator view. A logger is associated to one or many logging class defining the output channels.
This separation allows the developer to be isolated from the logging infrastructure and let the administrator
manage the locations of the log files without disturbing the application behavior.
The following example shows a part of the logger.xml used to define the default logger of the Portal Runtime.
<Logger
name = "default_logger"
loggerInterface = "com.sapportals.portal.prt.logger.ILogger"
isActive = "true"
pattern = "%d # %20t %15s %m #">
<LoggerClass
className = "com.sapportals.portal.prt.logger.SimpleFileLogger"
level = "WARNING">
<param
filename = "logs/workplace.log"
append = "false"
limit = "800000">
</param>
</LoggerClass>
<LoggerClass
className = "com.sapportals.portal.prt.logger.ConsoleLogger"
level = "SEVERE"
>
</LoggerClass>
</logger>
The first access to such a component will indicate to the Portal Runtime framework to compile the JSP into a
real IPortalComponent instance and then execute it. The location where to find the JSP is the property "JSP"
In that case, the PRT will find a JSP called checkresult under the directory jsp.
The second example shows how to access to JSP files belonging to another Portal Application.
In that case, the PRT will find a JSP called foo under the directory jsp in the component JSPValidation.
Directory Description
any path Contains the page that will be compiled into a Portal Component
The JSP file is compiled when the Portal Component is accessed for the first time. The JSP file found is
generated into a java Portal Component file and then compiled into a class file. The structure reflects the java
packages.
For example a file named jsp/select/customer/default/entry.jsp will be compiled under the package name
jsp.select.customer.default in file _sapportalsjsp_entry.java.
#
# This specifies jars to add to the classpath for JSP compilation
#
jsp.addclasspath=C:/Java/jdk.1.3.1_01/lib/tools.jar;
After compilation, the generated classes are added to the class loader of the Portal Component.
Page directive
The page directive accepts the following parameter:
The following table shows the actual support of the page directive in the Portal Runtime:
include directive/action
The include directive is used to include text and/or code at JSP page translation time.
The include action is used for the inclusion of static and dynamic resources in the same context as the current
page.
Examples
The following example requests the inclusion, at translation time, of a copy-right file. The file may have elements
which will be processed too.
<%@include file="copyright.html " %>
Syntax
<%@include file="relativeURLspec "%>
The relativeURLSpec is relative to the private resource Portal Component distribution file.
Property Value
tlhtmlb /SERVICE/htmlb/taglib/htmlb.tld
The JSP file that is referencing the tag library can use the custom tag library definition property to reference
the tag Library as follow:
<%@ taglib uri="prt:taglib:tlhtmlb" prefix="hbj" %>
Java Beans
Java Beans referenced in JSP must be accessible at compilation time and at execution time. This accessibility
is achieved by packaging the beans into the lib or classes directory of the PAR file.
Passing a Java beans to the JSP page can be achieved by storing the beans into the request.
The jsp:useBean action associates an instance of a Java programming language object defined within a given
scope and available with a given id with a newly declared scripting variable of the same id.
The jsp:useBean action is quite flexible; its exact semantics depends on the attributes given. The basic
semantic tries to find an existing object using id and scope . If the object is not found it will attempt to create the
object using the other attributes. The JSP semantics is respected when translating a JSP page to a Portal
Component.
However the name spacing associated to the application scope is modified and is associated to the context of
the Portal Component like in the example below:
When using the application scope, the beans instance is stored in the context of the component that is using the
JSP page that contains the useBean directive.
• page - Objects with page scope are accessible only within the page where they are created. References to
objects with page scope are stored in the pageContext object.
• request - Objects with request scope are accessible from pages processing the same request where they were
created. References to objects with request scope are stored in the request object.
• session - Objects with session scope are accessible from pages processing requests that are in the same
session as the one in which they were created. References to objects with session scope are stored in the
PortalComponentSession object associated with the page activation.
• application - Objects with application scope are accessible from pages processing requests that are in the
same application as the one in which they were created. References to objects with application scope are stored
in the component context associated of the Portal Component that activates the page. All references to the
object shall be released when the runtime environment reclaims the PortalComponentContext.
<% logger.setComponentRequest(componentRequest);
IPortalRequestEventData data = componentRequest.createRequestEventData();
IPortalRequestEvent loEvent = componentRequest.createRequestEvent("oneEvent",data);
%>
<!-- Gets all logger names from admin logger service -->
<FORM type=POST ACTION= <%=
componentRequest.createComponentURL(componentRequest.getNode(), loEvent)%> >
<br/>
…
<components>
<component name="MyComponent">
<component-config>
<property name="ClassName" value="com.sapportals.portal.MyClass"/>
</component-config>
<component-profile>
<property name="timeout" value="2000"/>
</component-profile>
</component>
</components>
…
If this constructor is used the timeout cannot exceed this value even if the component has defined a longer
timeout in its profile.
Below a simple example : A component includes 3 nodes asynchronously and writes the content to the original
response.
- node 1 takes too long to render (timeout case) and has an obsolete cache.
- node 2 has no cache content and has enough time to finish its rendering
- node 3 has some valid cache content (does not need to rendered)
resp.writeToParentResponse ()
}
Time
resp.asyncInclude (node1)
Main thread
Check for Node1 Cache Content: Not up to date, launch a rendering thread
resp.asyncInclude (node2)
Check for Node2 Cache Content: Not available, launch a rendering thread
Thread 1
resp.asyncInclude (node3)
Check for Node3 Cache Content:
Thread 2 available and valid, return cache
content
resp.waitUntilAllIncludesDone ()
A H
AbstractPortalComponent 12 Hook
Alias 86 Deployment Hook 79
API Portal Hooks 37
Asynchronous Response API 109
I
Component Event API 41
Dispatcher API 26 InitialContext 43
Event API 40 INode 34
Portal Runtime API 11 Internationalization 80
Application Configuration 16 IPortalComponent 11
Application Dependencies 24 IService 12
Application Life Cycle 23 IServiceContext 12
Application Repository 23, 32 IStreamSource 94
C J
Cache 31 JCO Client Service 61
Central Configuration Storage 94 JNDI
Class loading 42 Class loading 42
Class Loading 90 Initial Context 43
EP 5.0 56 JNDI Clients 43
ClassName 18 JNDI Packaging 43
Compatibility issues 56 JNDI Provider Resource File 44
Backward compatibility JNDI Service Providers 42
EP 5.0 56 jndiprovider.properties 43
UNIX/Windows 57 JSP 102
Component compilation 103
Component Configuration 18 Component Type 102
Component Type 102
Component L
Component Profile 19 Locale 81
Component Type 18, 96, 102 Logger 101
ConfigRootFolder 19, 66
Configuration Framework 65 M
Content Abstraction 97 Mode
Content Conversion Service 59 Component Mode 35
Core Application 9 Test Mode 98, 100
D N
Deployment Notification Service 58
Deployment Hook 79
Hot Deployment 24 P
Local Deployment 88 P.O.M. See Portal Object Model
Deployment Descriptor 16, 92 PAR Deployment 77
Deployment Policy 78 PAR File 14
EP 5.0 56 EP 5.0 56
Directory structure 88 PAR Flow 77
E PAR IDE 53
PAR Upload 77
Exception Handling 73 Permissions 83
Exception Catalog 76 Portal Application 9
Exception Files 75 Portal Application archive See PAR File
Portal Component 11