Prtguide 60

Portal Runtime –
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
Introduction and Positioning

The Portal Runtime is one basic part of the SAP Enterprise Portal Environment integrated in the SAP J2EE
environment.
The Portal Runtime Technology provides a Java based framework to define, build, and execute Applications
in a Portal Environment by allowing the aggregation and the display of various contents such as rich text,
xml, videos etc…
The Portal Runtime Technology provides a runtime and its corresponding services as well as a development
environment for Portal applications. The motivation behind the design and the technical implementation of
the Portal Runtime are the following:
• Area of concern:
The goal of the PRT is very well identified and restricts itself to the life cycle of portal applications.
• Open and Extensible:
Many of the components of the PRT can be changed or customized to be adapted to the
environment in which the PRT is executed. So the model proposed by the PRT can be extended to
support, for example, different user interface models or different programming models.
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 Runtime Technology Page 6 /113

Concepts and Terminology
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 Application Archive (PAR files)

A PAR file is an archive file containing a Portal Application. A PAR file contains the Portal Application
Deployment Descriptor (portalapp.xml). This file describes the portal application itself and provides
information required at runtime.
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.
Portal Component Profile

The component profile is a set of properties (name-value pairs) representing the dynamic part of a Portal
Component that could be customized to change the behavior of a Portal Application.
Portal Component Config

The component config is a set of properties which configures the Portal Component (class name etc…).
Portal Runtime Mode

Portal Runtime Mode allows a Portal component to display a different user interface according to the
specified mode.
Portal Object Model (P.O.M.)

The Portal Object Model is a runtime representation of the portal structure at request time. It is a hierarchical
representation of the components participating in the processing of a request and in the construction of a
response.
It is the underlying structure of all server-side eventing and it serves as a logical representation of the Portal
structure for addressing the request events.
The POM is only valid during one request. The state is not kept on the server side.

Application Repository
The Application repository is the persistence layer of the Portal Runtime. It contains every object persisted
by the Portal. In its most basis form, it offers a JNDI access to Portal Applications. It also takes into account
the application distribution in a cluster installation.

2 Portal Infrastructure
This chapter describes the Portal Runtime Infrastructure. The main motivation behind the design of the
Portal infrastructure is to isolate Portal Application from the environment.
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.
SAP J2EE Application Server
SAP J2EE Services
PRT Bridge Service

Core Applications
Servlet Container
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.

The table below shows the list of the main Portal Runtime core applications.
Application name Description

com.sap.portal.runtime.system.repository The application repository itself.
com.sap.portal.runtime.system.console The runtime console giving access to the
administrative tools of the Portal Infrastructure
com.sap.portal.runtime.system.notification The notification service relies on the PRT Bridge to
send and receive from one PRT to another
com.sap.portal.runtime.system.authentication Security functionalities to authenticate a user in the
Portal.
usermanagement User management implementation service.

3 Portal Runtime API
The central piece of the Portal Runtime technology is the Portal Runtime API. It contains Java interfaces that
define the contract between the Portal objects (Applications, components, services) and the Runtime
environment.
The following table describes the main elements of the API. The objective of this chapter is to describe the
main important interfaces of the API. The complete API documentation can be found in the Portal Runtime
javadoc.
API ELEMENTS JAVA NAME DESCRIPTION

Portal Component IPortalComponent The IPortalComponent is the
central abstraction of the Portal
AbstractPortalComponent
Runtime API. It defines a Portal
IPortalComponentInit Component included in a Portal
Application
Portal Service IService A Portal Service included in a
Portal Application.
Profile IPortalComponentProfile A set of properties attached to a
Component or a Service.
IServiceProfile
Configuration IPortalComponentConfig The configuration of a
component or a service (static
IServiceConfig
immutable).
Request IPortalComponentRequest The Component’s view on the
request during Runtime.
Response IPortalComponentResponse Encapsulation of information
sent to the client by a Portal
Component.
Portal Event IPortalRequestEvent This is the API to receive and
send events with the client’s
IPortalComponentEvent
request or between different
components.
Context IPortalComponentContext A view of the context in which
the Portal Runtime runs
IServiceContext
Components and Services.
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.

• Destroy() The Portal Runtime calls the destroy() method when the Portal Component is discarded
from memory either because the Portal is terminating or because the Portal Runtime needs to free up
some memory or during the release of its corresponding application when uploading a new one for
example. The garbage collector then collects the Portal Component.
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.

Request/Response
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.

4 Portal Application Archives
PAR File format

This chapter describes the Portal Application archive format and how the format is used and interpreted by
the runtime.
A PAR file contains all the file-based resources that make up a Portal Application. Resources of a Portal
Application fall into the following two categories:
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

The following picture shows an example of a typical PAR file structure:
<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.

Structure of the Deployment Descriptor
The deployment descriptor (portalapp.xml) is noted as an XML definition. The root element is the application
element. The application element may have an attribute alias, containing a comma-separated list of aliases
on the portal application. These aliases can be used alternatively to the real application name, the name of
the containing PAR file, when referencing the application (see Application Configuration Properties) and
Portal Components (see Portal Components).
Note: The concept of aliases is meant to be used for backward compatibility reasons. It effectively reserves a
name some other application potentially would like to use. So use it with care.
Portal Application
Within the application element the following child elements are allowed:
Application-config see Application Configuration Properties

Components see Portal Components
Services see Portal Services
Example:
<?xml version="1.0" encoding="iso-8859-1"?>#
<application alias="com.abc.my.other.name">
<application-config>
...
</application-config>
<services>
...
</services>
<components>
...
</components>
</application>
Portal Application Configuration

The application-config element may contain as many number of property elements as you like. The
properties specified in this section of the deployment descriptor affect the Portal Application as a whole.
The first thing to know is that the name of the application is the name of the PAR-file.
A property element declares a property by name and value. For example
<property name="myProperty" value="myPropertyValue"/>
The following table describes currently meaningful application configuration properties:
Name Description Admissible value Default

SharingReference This property allows references to other comma-separated list n.a.
Portal Applications whose API definitions of other Portal
are to be used in this application's API Application's names or
definition. See also Class Loading in the aliases thereof.
Portal Runtime.

PrivateSharingReference This property allows references to other comma-separated list n.a.
Portal Applications whose API definitions of other Portal
are to be used in this application's (non- Application's names or
public) implementation. See also Class aliases thereof.
Loading in the Portal Runtime.
ClassLoadingPolicy The values of this property affects the Comma-separated "transitive"
way class loader resources are exposed combination of
by this application to other applications
"5.0",
and more. See also Class Loading in the
Portal Runtime. In particular, this "coreAccessInAPI",
property is also used for backward
compatibility since it can be used to "transitive"
enforce the 5.0 behavior. See also
Compatibility Considerations.
startup If set to "true", the application as a whole "true", "false" False
will be "started" (initialized) on startup of
the server. In particular this means that it
will be locally deployed.
releasable Because PRT allows hot deployment, all "true", "false" True
applications are releasable and the
application instance can be dropped at
any time by the system.
Nevertheless some critical applications
may want to avoid the release of their
instance when the system runs low in
memory. They should then set this
property to false.
The following properties are mainly kept for backward compatibility with 5.0. In general see also
Compatibility Considerations.
Name Description Amissable Values Default

PreservedConfigPaths Depending on the deployment policy (see A comma-separated list n.a.
above), it is possible to specify a number of application local paths
of folders in the PAR that are to be (e.g. PORTAL-
preserved during local deployment. INF/mystuff).
See also Compatibility Considerations.
DeploymentPolicy This property affects how the Portal "5.0" or <empty> n.a.
Application's resources are treated during
local deployment. See also Compatibility
Considerations
ServicesReference This property is equivalent to the see above see
SharingReference property. above

Portal Components
All Portal Components of a Portal Application are declared in component sections contained in the
components section. The following XML attributes apply to the component section:
Name Description Mandatory

Name The portal component name within the yes
application. An absolute Portal Component
Name is constructed as <application
name>.<portal component name>. This
attribute specifies the <portal component
name>.
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>
...
Portal Component Configuration

The component-config section within a component section of the deployment descriptor contains properties
that enable the use of a Portal Component with the Portal Runtime. Each property is declared as described
in Application Configuration Properties.
The properties specified in this section are accessible to Portal Components via the interface
com.sapportals.portal.prt.component.IPortalComponentConfig.
The main properties the developer must be aware of are the following:
Name Description Mandatory Default

ClassName The name of the implementation class of No n.a.
the Portal Component.
ComponentType The type of the component. Admissible No <none>
values are: "servlet", "jspnative", <none>.
Default is <none>, in which case an
implementation of IPortalComponent has
to be specified by the ClassName property.

JSP In the case of no n.a.
ComponentType=="jspnative", the path of
the JSP PageLet to implement the Portal
Component. This path is relative to the
private resources (under PORTAL-INF in
PAR) of the Portal Application
ResourceBundleName A Portal Component can specify the name no "localization"
of a distinguished resource bundle. This
bundle will be used to look for descriptive
texts in generic personalization dialogs.
See text localization for more details
AuthRequirement Initial minimal authentication requirements no user:
to execute the Portal Component. authenticated
user
admin:
This Property is only supported for
administrator
backward compatibility reason. The 6.0
only.
version relies on the security zone concept
to control access to the Portal none: also
Components. anonymous
users
Role list : only
the roles that
are in the list
SecurityZone String representing the security zone, the no
component belongs to.
See Permission Model for components for
more details.
Portal Component Profiles

The component-profile section contains properties that make up the profile of the Portal Component as
accessible from the com.sapportals.portal.prt.component.IPortalComponentProfile
interface at runtime. The profile is usually abstracted in a personalizable entity, the iView.
The values of properties in this section define the default values. By administrative modification or
personalization, these values may be modified.
Some properties are PRT specific:
Name Description Possible values Default

ConfigRootFolder String representing the path /com.sap.myapplication.mycomponent
within the overall
configuration structure of the
component specific
configuration.
See Configuration
management for Portal
Application for more details.
CachingLevel Shared : The cache content is shared
among all users.
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
ValidityPeriod Time period in milliseconds
EPCFLevel Defines whether to use the 1: This component does not use the EPCF 2
Enterprise Portal Client at all. Therefore neither script nor applets
Framework or not. will be included.
2: This level includes all EPCF features that

use pure JavaScript
3: This level includes all features of level 1

and additional features that use applets.
If two or more embedded iViews with different

EPCFLevel values meet on one page (within
the same frame), the effective level is
computed as the maximum of all EPCFLevel
values on this page.
Each property in this section may have further attributes. Additional attributes describe how to handle the
properties with respect to personalization and meta-data handling. Attributes of profile properties are
denoted by sub-properties.
For example:
<property name="Color" value="red">

<property name="personalization" value="dialog"/>
<property name="type" value="select[red,green,blue]"/>
</property>
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:
Name Description Admissible value Default

description A text token that can be n.a. n.a.
resolved by accessing the
component's resource
bundle. It represents a
locale sensitive
descriptive text for the
property that can be used
in user interfaces.
plainDescription A plain text that can be n.a. the property
used in user interfaces to name.
describe the property.
This will be used if no
description attribute is
specified.

type A "visual" type of the select[<option>(,<option>)*], <none>
property to be respected
boolean,
as a hint by user
interfaces. <none>
personalization This attribute specifies none: cross-user storage, dialog
how to treat this property not shown in
with respect to personalization
personalization.
no-dialog: per-user storage,

not shown in
personalization
dialog: per-user storage and

shown in personalization.
inheritance specifies whether the final, non-final non-final
property can be
overridden by a template
derivation (e.g. iView
chain).
Portal Services
Portal Services are declared in service elements inside the services element.
The following XML attributes apply to the service section:
Name Description Mandatory

name The service name within the application. A fully yes
qualified Portal Service Name is constructed as
<application name>.<portal service name>.
This attribute specifies the <portal service
name>.
alias a name that can be used instead of the fully no
qualified service name (see above) when
looking up the Portal Service.
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>

Portal Service Configuration Properties
The service-config section within a service section of the deployment descriptor contains properties that
enable the use of a Portal Service with the Portal Runtime.
The properties specified in this section are accessible to a Portal Service via the interface
com.sapportals.portal.prt.service. IServiceConfig.
Properties of reserved meaning are:

Name Description Mandatory Default
className The name of the implementation class of the Yes n.a.
Portal Service. This class must implement the
IService interface.
startup If set to "true", the service will be started at No false

startup of the runtime. If not, the service will be
started on demand.
Portal Service Profiles

The service-profile section contains properties that make up the profile of the Portal Service as accessible
from the com.sapportals.portal.prt.service.IServiceProfile interface at runtime. In contrast
to the service config, the properties of the service profile may be modified by administrative environments
and is available at next start of the service. There are no predefined service profile properties.

5 Portal Application Life Cycle
This section describes the application life cycle and explains how and when information contained in the
PAR file is used to deploy Portal Applications and then to load the corresponding objects in memory.
First of all, it is important to understand that PAR files are stored in the application repository. There is only
one Application Repository and all PRT nodes of the SAP J2EE cluster are sharing the same content. The
Administrator will typically use admin tools to create the portal content; some of them (like the Archive
Uploader” are used to upload portal applications into the application repository.
Portal applications are also deployed locally (on each PRT node). The main purpose of the local deployment
is to improve performance by providing fast access to resources and avoid too many accesses to the
application repository. In that sense the local deployment is a cached copy of the original version; the local
version should not be modified directly.
Overview
DataBase server
PAR Upload Application Repository / Database
Web servers
Local Deployment / File system
HTTP Request
Application Broker Object

Instances

When a component or a service of a Portal Application is accessed for the first time (For instance
upon an HTTP request) the Portal Runtime has to load the implementation class and instantiate the
corresponding object. Internally the portal application broker checks whether the object is already
available and returns it.
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.

6 Portal Runtime Architecture
The objective of this chapter is to describe the architecture of the Portal Runtime by focusing on its
configuration and customization.
The figure bellow shows the main blocks of the Portal Runtime Architecture
Request Portal Portal Registry Portal Portal

Dispatcher Connection Component Application
API
Portal Runtime core Cache
Portal
Service API
Portal Application Repository
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
Property Description Default value

dispatcher.contactinfo If this situation persists, Default information message
please contact your displayed when a dispatcher
system administrator. exception occurs. The reason of the
exception is always displayed
before or in the source code of the
HTML page.
dispatcher.servlet.allow This defines whether an True
automatic forward to
another servlet is allowed
dispatcher.servlet.prefix This defines the pathinfo Servlet
prefix to be used
dispatcher.portal.root defines the portal root WEB-INF/portal
directory
dispatcher.portal. defines the portal default system/properties/prtDefault.propert
systemdefault.properties properties ies
dispatcher.portal.system.properties the portal properties system/properties/workplace.proper

ties
dispatcher.portal.defaultconnection The default connection portal
dispatcher.log.console console mode for the Verbose
dispatcher
dispatcher.version Automatically generated
version information
• 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:
Property Name Description Default value

portal.libs The directory below WEB- lib
INF/portal containing the public
library of the Portal Runtime
portal.classes Same for the public classes classes
system/lib The directory below WEB- system/lib
INF/portal containing the non-
public library of the Portal
Runtime
system/classes Same for the non-public classes system/classes
portal.protected.classes Prefixes for class names that will com.sun.xml.,
not be seen from the dispatcher javax.mail.,com.sun.mail.,
and below javax.activation
portal.protected.resources Same for resources localization, META-INF
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.
Library name Description

prtdispatcher.jar The code of the dispatcher itself
prtjndisupport.jar JDNI support in PRT.
prtregistry.jar API of the Portal Registry
prtutil.jar Utility classes of the Portal Runtime.
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.

Portal Runtime API
It defines the contract between the Portal Application and the Portal Runtime. The Portal Runtime API is
delivered in a set of 5 JAR files. This is the API to build Portal Components and Portal Services, but also the
API to cooperate with the infrastructure to extend it and customize it.
JAR name Description

prtapi.jar The Portal Application API.
prtconnection,jar The Portal Connection API to develop and install a
new connection in the Portal.
prtdeploymentapi.jar API to handle the format of PAR Files and the
deployment descriptor.
prt_jspapi.jar JSP support in Portal Runtime.
prttest.jar Portal Runtime Testing Framework API.
Portal Runtime Core

The Portal Runtime Core offers one implementation of the API.
It also manages the Portal Application life cycle and isolates Portal Application between them by
implementing the class loader separation.
The Core implementation is delivered in a set of JAR files described in the table below and packaged by
default in the WEB-INF/portal/lib directory.
JAR name Description

prtcore.jar The Portal Runtime core.
prtdeployment.jar Helper class implementation to handle the format of
PAR Files and the deployment descriptor
prtgluer.jar Utility classes of the Portal Runtime.
prtlogger.jar Default logger implementation.
concurrency.jar Concurrent thread access.
Changing the two following files located in the WEB-INF/portal/system/properties can customize some of the
functionality of the Portal Runtime Core.
File name Description

prtDefault.properties Default value for the properties of the PRT.
prtCentral.properties This file contains Properties that are going to be
stored in the Portal Registry. During its first startup,
the Portal Runtime reads this file and stores the
corresponding objects into the registry. When this
operation finishes successfully, the file is renamed
with a .bak extension.
prtUpdate.properties, prtDelete.properties Internal Portal Runtime file, used to manage upgrade
of the version of the Runtime.

The following table gives a list of the most important properties that can be changed to customize the Portal
Runtime behavior.
Name Description Default Value

runtime.doubleByteSupport
Indicates if the Runtime will true
support double byte encoding in
the request and the response
The type of encoding to use UTF-8
runtime.doubleByteSupport.encoding
when double byte support is
activated in the PRT
async.response.pool.size
The pool size for the 100
asynchronous response
mechanism
async.response.timeout.pool.size
The thread pool size to manage 100
the timeout when using the
asynchronous response
mechanism.
default.component.timeout
Timeout for the components 10000
participating in the construction
of the asynchronous response.
request.defaultlanguage
This is the default language to be En
used when none is specified
request.defaultcountry
Same for the country. us
personalization.defaultDelegate StandardEditDialog
Default delegate for the
personalization of a component
caching.off false
If the PRT cache must be turned
off by default.
Monitor.off True
If sets to true, monitoring is
switched off.
connection.defaultcomponent PortalAnywhere.default
The default Portal Component to
start when none is specified.
jsp.addclasspath
Classpath element to add when
compiling a JSP in the Portal
Runtime
loadlimit.requests -1
Number of maximum concurrent
requests managed by the PRT.
portal.runtime.permission.mode If set to development prtroot production
access is allowed for every
component.
If set to test prtroot access is
allowed for every component that
doesn’t belong to a specified
zone.
If set to production prtroot
access is not allowed unless the
component belongs to a security
zone. In that, the access to the
security zone is tested.
See Security Zone in PRT.

Portal Registry
The Portal Registry is the entry point for inspection of almost all Portal runtime information. In particular, this
includes the running services and the Portal Configuration. The Portal Registry is implemented as a
hierarchical JNDI context allowing to bind any kind of object.
In general, the Portal Registry is used for two purposes:
• A global place for an application to store and retrieve objects. The Portal Registry is a singleton
offering methods to create sub-contexts, bind, and lookup objects.
• The Portal Runtime is using a set of pre-defined contexts to store objects that are invoked at certain
point of time during the Portal execution.
The following table gives the list of contexts, in which the Portal Runtime will look for objects to customize its
execution.
Registry Sub-Context Description

runtime/hooks/node The list of node hooks.
runtime/hooks/component The component hooks list.
runtime/hooks/document The document hooks list.
runtime/hooks/response Contains all the response hooks known by the runtime.
runtime/hooks/deployment The context in which deployment hooks bind themselves in
order to be notified when a Portal Application is deployed in the
Portal.
runtime/hooks/event The list of event hooks installed in the runtime.
runtime/hooks/event/request.listeners The list of request event listeners
runtime/hooks/mode The list of mode hooks.
runtime/connections The connections known by the Portal Runtime.
runtime/prt.modes The modes known and handled by the PRT.
Central Configuration Storage

The Portal Registry also provides access to 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;
...
Context context = PortalRegistry.getCentralConfigurationContext();

Context applicationContext = context.lookup(“MyAppName”);
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.

Portal Runtime Cache
The Portal Runtime implements by default a memory cache. This cache is used to store and retrieve the
content of components that want to be cached. In that case, only the content of the request of type “content”
will be stored in the cache.
A content developer has two ways to decide when and how a Portal Component needs to cache content.
• Configure the Portal Component by selecting a set of Properties.
• Using the Portal Runtime API to control the validity and the granularity of the cache. In that case, the
component needs to change its implementation and inherit from the ICachablePortalComponent
interface.
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.

Portal Application Repository
The Application Repository serves to provide information on all available Portal Applications (including Portal
Components and Portal Services). In Addition the Portal Application Repository provides a central storage of
application configuration and arbitrary application data.
The Application repository is packaged and delivered as a standard Portal Service providing a JNDI interface
to the following contexts:
Folder Name Description

com.sap.portal.system Root context
com.sap.portal.system/archives Folders for PAR files
com.sap.portal.system/applications Folder containing the list of applications loaded in
the repository.
com.sap.portal.system/configuration The configuration of the Applications.
Portal Connection Framework

The Portal Connection Framework offers an API allowing to control the process of a request. This layer
allows to plug several “Connection” implementation to the portal. Each implementation might have a different
request cycle.
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
Two connections are provided by default by the Portal Runtime.
Connnection Name Type Description

/runtime/connections/portal Servlet connection This is the default connection of the portal.
/runtime/connections/soap Soap connection Handle any incoming SOAP request.
Connection registration at startup:

The registration must bind an object of type IServletConnection in the “connections” JNDI context of the
Portal Registry. This can be done during the initialization of a service that has been marked as load on
startup.
public synchronized void init(IServiceContext context){

mm_connection = new MyConnection();
try {
PortalRegistry.getInstance().bind ("/runtime/connections/MyConnection",
mm_connection);
} catch (NamingException e) {}}

The IServletConnection interface has defined one method called:
• handleRequest(IDispatcherContext) The dispatcher context gives access to the environment
in which the connection has been started. It gives access to the request, and the response.

7 Request Cycle
The request cycle starts when the dispatcher receives an HTTP request and ends when the response is sent
back to the browser.
The Dispatcher selects the “Portal Connection” according to some information encoded in the URL. This
chapter describes the request cycle as it is performed by the default “Connection” used by the Portal
Runtime.
The default connection will perform the following steps:

1. User authentication.
Authenticate User attached to the request.
2. Uses JNDI to get the Portal Object that is to be rendered.
The name of the Portal Object to start is provided by the prtroot URL parameter.
For further detail concerning “Runnable Portal Objects” please check: Portal Content Abstraction
page 97.
3. Create the Portal Object Model (P.O.M.).
Create the request's Portal Object Model that represents the structure of all components in the portal
that participate in event handling and content creation within this request. During creation, the Portal
Runtime notifies the participating elements to create their sub structures in the Portal Object Model
and notifies them about their ready state.
4. Handle Request Event.
Raise any event defined by using an appropriately generated URL.
5. Start the content collection phase.
This is again a 3 steps phase:
a. Before content phase. A before content event is sent to all the nodes in the POM. All nodes
involved in the POM have a chance to perform special actions before the actual content
phase start.
b. Content phase. Retrieve the content of all the nodes present in the POM.
c. After content phase. An after content event is sent to all the nodes in the POM.
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.

The figure below shows a simple POM with 3 Nodes. The root node called Portal Node, a Node without any
component attached to it and a Node with its Component.
Portal Node
Component
B
Node a Node b
Portal Component Mode

Portal Component Mode allows a component to render a different User Interfaces (UI). Modes are
abstracting a context in which component can react and display an appropriate UI. Modes are supposed to
be general enough; every components must offer a support for it. So a mode must represent a situation,
which is often encountered by most of the Portal Components.
For that reason, the Portal Runtime handles a number of pre-defined modes:
• TEST, HELP, ABOUT, EDIT, LOGON, ERROR,
• CONTENT. The content mode is the default mode of operation when rendering a component.
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:
public void doHelp (IPortalComponentRequest request,

IPortalComponentResponse response)
{

response.write (“<BR> We are in help mode”);
}
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.
Default Mode Delegate

The delegation mechanism may be defined as a default way to handle a mode. To do so, a component
needs to declare itself as the delegate for a specific mode by binding this mode in a specific folder called
/runtime/prt.modes of the Portal Registry. In that case, invoking this bound mode on any component will
result in invoking the mode handling method on the delegate.
The setup of such a component is also done in the Portal Application configuration as shown in the following
example:
<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.
Mode Name Description System delegate

/runtime/prt.modes/edit Edit and save the profile of a StandardEditDialog
component.
/runtime/prt.modes/about Display a short text explaining SystemModes
the purpose of the component.
/runtime/prt.modes/help Display the help text of the SystemModes
component.
/runtime/prt.modes/preview Do a preview of the SystemModes
component.
/runtime/prt.modes/config Display the UI of the SystemModes
configuration framework
starting from the root plugin of
the component.
/runtime/prt.modes/test Start the component in a test SystemModes
mode. In that all the methods
signed starting with test and
signed with a TestResponse
will be invoked.
/runtime/prt.modes/error Used by the Runtime to display ErrorComponent
the error returned by a
component.
/runtime/prt.modes/badUserAgent Runtime internal usage. SystemModes
/runtime/prt.modes/_release Runtime internal usage. ReleaseComponent
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:

Adding a new Portal Hook
In general, adding a new Hook in the Portal Runtime will change the default behavior of all applications
loaded in the Portal. This makes the hooking mechanism, very powerful and also very dangerous. So the
usage of this API must be reserved for very few occasions.
This is the reason why the hooking API is packaged into the core of the Portal Runtime.
Adding a new Hook Portal is basically done in the following steps.

1. Deliver a system service that binds an entry in the Portal Registry hooks context.
2. This entry implements one of the Hook interface defined by the Portal Runtime Hook API.
a. IEventHook.
b. INodeHook,
c. IComponentHook,
d. IResponseHook,
e. IDocumentHook
3. Each hook implementation defines methods called during the hooks processing by the Portal
Runtime. At hooking point, the Portal Runtime will first traverse the list of hooks declared and then

perform the default behavior. During the hooks traversal, each hook returns a status that can have
one of the following value:
a. OK. The Portal Runtime will continue with the normal process after the hooks
chain traversal.
b. SKIP The hook chain is traversed, but the default Portal Runtime process is not
performed at the end of the hooks processing.
c. ERROR The hook indicates that it encounters a problem during its execution, but the
hook chain is still traversed and the default behavior is going to be executed.
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>
<property name="releasable" value="true"/>
<property name="startup" value="true"/>
<components>
<component name=" MyEventListener">
...
</component>
</components>
</application>

Event Handling
The Portal makes the distinction between two kinds of events:
• Request Events Events sent by the client set in the URL received by the WEB server.
• POM Events Events sent by a Portal Component to another.
Internal Portal Runtime Events

Several pre-defined events are raised by the Portal Runtime to inform the Portal Components involved in the
request processing of the progress of the request cycle.
IEvent.ON_NODE_READY_EVENT Means that the node/component has been assigned to its

parent node in the Portal Object Model on its construction
in the request cycle. Receivers that have to assign children
in the POM should do it upon handling this event.
IEvent.ON_POM_READY_EVENT Means that the node/component has been assigned to its
parent node in the Portal Object Model on its construction
in the request cycle. Receivers that have to assign children
in the POM should do it upon handling this event.
IEvent.BEFORE_CONTENT_EVENT Means that we enter content collection next.
IEvent.AFTER_CONTENT_EVENT Means that content collection is over. This is sent on a pre-
order traversal of the POM.
IEvent.ON_NODE_REMOVE_EVENT Means that the node is going to be removed from its parent
node. This is can be a good time to release all listener
assignments that depend on the current POM structure.
Request Event API

Request Event must be generated by the standard Portal Component API method used to create event.
Those events are then generated in the content of the Portal Component and the methods to handle the
events have to be written in the Portal Component.
The methods to create the event are defined in the IPortalComponentRequest Object
• IPortalRequestEvent createRequestEvent(String) creates a Request Event with the name
passed as parameter.
• IPortalRequestEvent createRequestEvent(String ,IPortalRequestEventData) returns a request
event corresponding to the name and containing the data passed as parameter.

Component Event API
Component Event is a mechanism to send and receive special type of POM events which have name and
data. It allows a component to listen and filter events sent by others components.
The sender component should create a component event and fire it using the Portal Component API.
The receiver component should listen to events and react when the events are received.
Those events are generated by the Portal Component API using the following methods on the portal node.
• IPortalComponentEvent anEvent createPortalComponentEvent (String name)
Events are then published by calling the fireEventOnNode method of the Portal Node of the POM. A
component event should be fired on the portal node only.
• fireEventOnNode () publish the event to all the nodes of POM.
• addEventListener (EventType.COMPONENT_EVENT, IEventListener, IEventFilter) declare an
Event Listener and attach an Event filter to receive only events in which the Portal Component is
interested
Helper class is provided for component events (AbstractComponentEventFilters).
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.

8 JNDI Support in PRT
The standard JNDI way to get access to JNDI Factories assumes that the JNDI service provider classes are
in the class path. Unfortunately PRT (like any J2EE engines) implements a class loading separation feature
that contradicts with the JNDI approach. This chapter explains how to use JNDI service providers without
loosing the benefit of class loading separation.
PRT JNDI Support Package

The PRT JNDI support package provides a different implementation of the following core JNDI classes:
javax.naming.NamingManager
javax.naming.DirectoryManager
javax.naming.InitialContext
javax.naming.InitialDirContext
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.
JNDI Service Providers

To take benefit of the PRT JNDI Support, JNDI Service Providers will have to compile against this new
“com.sapportals.portal.prt.jndisupport” package and delegate to the PRT implementation instead of calling
directly the core classes provided by the “javax.naming” package.
import com.sapportals.portal.prt.jndisupport.DirectoryManager;
// convert the persistenceObject to a semantic object

Object semanticObject;
semanticObject = DirectoryManager.getObjectInstance( null,

name,
this,
env,
objectAttributes);

JNDI Clients
JNDI clients have to change the way they get the InitialContext. They must used the PRT Implementation of
the Initial Context class instead of the standard one like below:
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();
}
JNDI Service Providers Packaging

A typical JNDI service provider will be deployed in the portal like any portal application by providing a PAR
File. In order to register itself to the PRT JNDI Support, the application have to include a java property file
named jndiprovider.properties in its PAR File and be declared as “load-on-startup” in its deployment
descriptor.
The location of this “JNDI Provider Resource File” in the PAR file must be:
/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

JNDI Provider Resource File Sample
Let’s imagine a “Travel Management Portal Application” that want to plug its own content to the portal. This
application could have its own factories and its own scheme (tm:).
A typical “JNDI Provider Resource File” could be:
#
# 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 Concepts and Related Documents

The JNDI Tutorial provides in-depth information concerning the JNDI API and how to implement it.
JNDI Tutorial: http://java.sun.com/products/jndi/tutorial/
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.

More detail at: http://java.sun.com/j2se/1.3/docs/api/javax/naming/Context.html
JNDI Context Factories

The initial context factory is the object used to create initial context instances. Factories are necessary
because only the factory knows about the context implementation.
The JNDI Naming Manager internally used factories to get Context instances.
More detail at: http://java.sun.com/j2se/1.3/docs/api/javax/naming/spi/InitialContextFactory.html

9 WEB Services Support
A natural extension of the concept of Portal Services is the WEB Services technology. By providing a SOAP
connection to the Portal Services, external components can access to the services and applications
developed with the Portal Runtime technology using the SOAP protocol. In the same way, the Portal
Runtime provides tools and facilities to generate Proxies to external WEB Services. Thus, Portal
Components and Portal Services can easily access to external WEB Services to build Portal Applications
The purpose of this chapter is to describe how work WEB Portal Services.
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 as WEB Services

Turning a Portal Service to a Web Service is something very smooth and easy after using the open tool
(ToolKitWebServicePRT). A simple modification of the portalapp.xml makes the trick. The following line must
be added : WebEnable=”true” (If you want to use a proxy, generated with the ToolKitWebServicePRT you
have to set the property WebProxy=”true”) . This done, the Portal Service is a Portal Web Service. The
WSDL file informs what are the accessible methods in the service. It is accessible via an URL of the type :
irj/servlet/prt/soap/PortalServiceName?wsdl .
Portalapp.xml property Effect

WebEnable=”true” Turn the service into a WEB service
WebProxy=”true” Force the use of the proxy of the service
Portal Applications and external WEB services

External WEB services can be accessed by portal components or portal services.
Portal .NET WEB

Components /
SOAP SERVICE
INQMY
Service SOAP Protocol /
SOAP IMPLEMEN
LAYER
APACHE TATION
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

(ToolKitWebServicePRT) allows you to configure your development environment. The open tool do almost
all the work needed.
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
Implementation Wrapper Generator Implemen

-tation D
SOAP
Service E
V
Service SOAP
R
Invocation Consumer SOAP U
Service
N
WSDL SOAP T
Soap Service Service Connection PRT Service I
SOAP Message M
E

Architecture
In this part, the main architectural aspects of the portal WEB services will be detailed.
IService Open Tool . wsdl From

External Service
Simple and
IXXXService Complex
Types
methodA
…
methodB
IX.wsdl Open Tool
Open Tool
Proxy
SOAPProxyP + Connection
Information
Par
Reflection
WEB Service development process
1. Soap Framework
SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is

an XML based protocol that consists of three parts: an envelope that defines a framework for describing
what is in a message and how to process it, a set of encoding rules for expressing instances of application-
defined data types, and a convention for representing remote procedure calls and responses. SOAP can
potentially be used in combination with a variety of other protocols; however, the only bindings defined in this
document describe how to use SOAP in combination with HTTP and HTTP Extension Framework.
A Web Service is an interface that describes a collection of operations that are network-accessible through
standardized XML Messaging.
WSDL is an XML format for describing network services as a set of endpoints operating on messages
containing either document-oriented or procedure-oriented information.

1.1 The Portal WEB Services give a common architecture to connect external Web Services.
In this case, the Portal Runtime will also provide his own implementation to generate proxy for Web services
Connection. The developer, which needs to contact external Web Services, will also use the portal WEB
services implementation to the address them.
The open tool is able to generate a portal service from a WSDL file.
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
One unique entry point

The advantage of this approach is that there is no need to provide multiple URL, to be connected. It also
allows us to only provide one ServletConnection to understand SOAP Calls.
These URLs are of this type :
irj/servlet/prt/soap/AliasApplication

irj/servlet/prt/soap/ApplicationName.ServiceName
Easy use of Portal Services

The Portal Runtime Services are called dynamically by the SOAP Listener (or Consumer). The developer of
the Portal Services will have to provide a few extra works.
The service developers need to provide:
- The exposed methods wanted, selected with the open tool
- Modify the “portalapp.xml” file (description of the portal applications) to declare the service as
WebEnabled (proceed the same way for the WebProxy).
- Create the associated PAR file and upload this PAR file.
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

The open tools can generate a proxy for each portal service turned into a WEB service. The proxy
externalizes the method call. The service then manipulates the proxy for its soap calls.
The proxy is automatically created, on request by the open tool, it wraps all the requested methods and
decompose them. The whole process is once more hidden from the user.
The proxies are also used for the call of external WEB services.
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.
8. SOAP Fault Process

• The invoked method generates an exception
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>
<faultactor>%[SERVER_NAME] COMPONENT NAME%</faultactor>
<detail>
<stackTrace >%JAVA_STACKTRACE%</stackTrace>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>

In SOAP Admin tool, it is possible to disable the display of java stack trace in the SOAP Fault Message. For
that the property “Debug Mode” must be deselect in the configuration menu.
• The SOAP Call return a fault message
WEB SERVICE SOAP FRAMEWORK

SOAP Request 2
3 1
PRTSOAP Call Web Portal Service
Error
Server SOAP Response
(Fault) SOAP Fault Message
4 Create 5
SOAP Fault Message
PRTFault Throws PRT Fault Exception
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).

10 PAR IDE
The PAR IDE is an eclipse plugin supporting the Portal Application development model. The objective of the
PAR IDE is to speed up the Portal Application development process.
It allows to:
• Import PAR file
• Export PAR file
• Add a Portal Object to a PAR. Supported objects are Portal Components, Portal Services, Portal
WEB Services.
• Create a Portal WEB Services from a WSDL or Portal Service
The complete documentation can be found in the iView studio WEB site: http://www.iviewstudio.com/
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
Portal Application PRT

Create PAR IDE Development Cycle
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.

You can interfere with both process concerning the packing and unpacking of the PAR file. During the
packing operation, the additional tool will be called before the final packing of the PAR file. And during the
unpacking operation, the additional tool will be call after the initial unpacking of the PAR file. In order to
create such a tool, you have to produce a PAR plugin add-on.
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.
In the plugin.xml the following extension point has to be added.
<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.
3. The interface to implement
To register, an add-on plugin must implement the

com.sap.portal.developmentTools.general.api.IparIdePlugin and give the implementation
class as parameter when it registers.
4. Other important notes
The add-on plugin has to clearly specify the final state of the operation using the method
setFinalState(int status) from the class

com.sap.portal.developmentTools.general.api.IfinishResult. If the final state is OK or
warning then the PAR process will go on otherwise it will be stopped. Inside the IfinishResult, you can also
add as many messages with their level as you want. These will be displayed into the task view of Eclipse.

11 Compatibility Considerations
EP 5.0 Backward compatibility

The following section describes some mechanisms that were kept or introduced in the 6.0 version to enable
backward compatibility
EP50 Deployment Policy

The local deployment of a portal application is done taking care of the “DeploymentPolicy” property declared
in the application config section of 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 the deployment process simply
overrides the folder with the new content.
- In that case the deployment policy also takes care of the deprecated “PreservedConfigPaths”
property. This property provides a comma-separated list of paths or file names that are
protected. Those files and paths will not be replaced by the new version.
EP50 Class Loading

"ClassLoaderPolicy": if set to "5.0", API definitions of referenced Portal Applications via the
"SharingReference" property will not be visible to referencing applications automatically. By default they will.
See also Class Loading in the Portal Runtime. The 6.0 model assumes that definitions made accessible via
the "SharingReference" property can be considered part of the Applications API and should therefore be
also made visible to a referencing application.
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.
Example of deployment descriptor enabling backward compatibility properties
<?xml version="1.0" encoding="utf-8"?>
<application name="com.sap.km.application" alias="knowledgemanagement">

<property name="releasable" value="false"/>
<property name="PreservedConfigPaths" value="/PORTAL-INF/lib/config_local.properties"/>
<property name="ClassLoadingPolicy" value="5.0"/>
<property name="DeploymentPolicy" value="5.0"/>
<components/>
<services>
<service name="default" alias="knowledgemanagement">
<service-config>
<property name="className" value="com.sapportals.wcm.portal.service.KMServiceImpl"/>
<property name="classNameFactory" value=""/>
<property name="classNameManager" value=""/>
<property name="poolFactory" value="0"/>
<property name="startup" value="false"/>
</service-config>

</service>
</services>
</application>
List of Incompatibilities to EP 5.0

• jco service is deprecated
• jcoclient service: the different getJCOClientPoolEntry() methods throw a TimeoutException (a
RuntimeException); this is the same in EP 5.0 since SP 4.2
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

12 Additional PRT Services
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
Notification Service Notification Service
PRT Bridge PRT Bridge
SAP J2EE cluster configuration

Content Conversion Service
Application name: com.sap.portal.runtime.application.contentconversion
In general Portal Components are generating HTML content, but a Portal Component can decide to
generate content of another type like XML or WML. Such a component can also participate in a WEB service
scenario. The Content Conversion Service allows Portal Components to generate such alternative content
types. It uses internally the PRT mechanism of a response hook. A component that wants to generate a
content type other than HTML must specify the property:
ContentType
in its configuration. The value of ContentType must be the text representation of an instance of
PortalComponentContentType, e.g.
text/wml
At runtime such a component receives a PortalComponentResponse in which the component can write
multiple content types. After the component has finished its content generation, a conversion of the content
takes place. The target content type of this conversion is the content type defined by the PortalResponse.
The content type defined by the property ContentType is the content type a component generates at the
beginning of the content generation. If a component wants to change the content type during generation, it
can call the method:
public void setContentType(PortalComponentContentType type)
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:
String convert(String content, IPortalComponentRequest request)
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:
public IContentConverter getConverter(PortalComponentContentType fromType,

PortalComponentContentType toType)
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.

The key to register the factory must be the concatenation of the two content types that the factory is able to
provide a converter for. The two content types must be URL encoded. Here is an example that registers
myFactory to provide a converter that can convert from RSS to HTML:
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);
Content Converter Service

Application name: com.sap.portal.runtime.application.contentconverter
This service provides a generic XSLConverter that implements IContentConverter (see Content Conversion
Service). The Content Converter Service registers during startup the following content converter factories:
RSS -> HTML
XML -> HTML
The converters provided by these factories are instances of XSLConverter. Instances of XSLConverter are
used to do conversions using XSL style sheets. An XSLConverter can be created by specifying a style sheet
to be used or/and the converter can look for a style sheet at runtime in the components resources. This is
the constructor of XSLConverter. See the API documentation for more details:
public XSLConverter(File styleSheet, String styleSheetReference) throws

FileNotFoundException

JCO Client Service
Application name: com.sap.portal.runtime.application.jcoclient
This service is used in EP 5.0 to provide JCO clients to Portal Components. It exists in EP 6.0 as well for
backward compatibility reasons. The recommended way to obtain JCO connections with EP 6.0, however is
the connector framework. Please refer to the corresponding documentation therefore.
The JCO Client Service provides the following functionality:
• Provide JCO clients to Portal Components
• Connection pooling
• HTTP session timeout detection
• Close connections when user logs off
• Maintain a connection limit (configurable)
• Authorization Trace (configurable)
Following is a usage scenario to explain this functionality:
User 1/ Session 1 User 1/ Session 2 User 2/ Session 1
a
a
c
a b
c
b b
Portal Runtime
d JCO Client Service
R/3 R/3
System 1 System 2
f

In the above scenario User 1 is logged on with two different sessions and User 2 with one session. It is
assumed that both users use the R/3 System 1 and System 2. In this scenario the JCO Client Service
provides the following functionality:
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.

RFC Engine Service
The RFC Engine Service allows to invoke a Portal Service from a R/3 system via an ABAP call to the
Portal Runtime.
The implementation of the RFC Engine Service is based on the rfc-engine service provided by
SAPJ2ee. This service knows and maintains a list of EJBs accessible from R/3 system via a RFC. The
PRT RFC Engine Service registers itself to the SAP J2EE service as an EJB.
Service Description
• Portal services that want to be called via RFC must implement a new interface
com.sapportals.portal.prt.service.rfc.IPRTRFCListener.
public class TestRFCEngineService implements Iservice, 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)
IRFCEngineService service = (IRFCEngineService) mm_serviceContext.getService

(IRFCEngineService.KEY);
service.setFunctionCallListener ("MY_R3_FUNCTION", “My Service or application

name”);
• The Portal Application has to reference the PRTRFCEengine Service.
<application alias="TestRFC">
<property name="ServicesReference" value="RFCEngine"/>
• Finally, the Portal Service must implement the function handleRequest to receive calls from
R/3 system.
public JCO.Function handleRequest(JCO.Function function, IUserContext userCtx)

throws Throwable {
try {
JCO.ParameterList input = function.getImportParameterList();
JCO.ParameterList output = function.getExportParameterList();
JCO.ParameterList tables = function.getTableParameterList();
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;

Implementation
1- On start-up, The PRTRFCEngine service is registering itself to the PRTBridge Service, under
the name “PRT_RFC”.
2- On its start-up the Portal Service listener of RFC registers itself to the PRTRFCEninge
Service.
3- The PRTRFCEngine is registering the new Function to the SAP J2ee RFCEngine service.
This triggers the registration of an EJB call PRTBase to the SAP J2EE RFC Engine.
4- When an R/3 System calls a function for the registered RFC-destination, it looks in its
context, to find which is the EJB registered under the function name.
5- The PRTBase EJB transmits the call to the PRT Bridge, by asking for the IRFCListener
registered in the bridge under the name “PRT_RFC”.
6- The EJB transmits the call the PRT RFCEngine
7- The Portal RFC engine transmits the call to the Portal Service, which registered the function
name. This Portal Service has to implement the interface
com.sapportals.portal.prt.service.rfc.IPRTRFCListener and so to define the method:
JCO.Function handleRequest (JCO.Function function, IUserContext userCtxt).
Security Open Issues

We need an authenticated Portal user in order to interact with some Portal services when being called
via RFC. With the version SAPJ2ee 6.20 of the rfcengine service, we are not able to know what is the
R/3 user, which had generated the calls.
With the actual version ramp-up and SAP J2ee, in method handleRequest, the parameter
IUserContext is not fill in. This issue will be fixed in the future version.

13 Configuration Management in Portal Application
The objective of this chapter is to describe how a Portal Application can define, load and manage its
own configuration in the Portal. This functionality is based on the Configuration Framework delivered
as one of the core services of the Portal Runtime: the Configuration Framework Services.
This Framework offers a set of libraries to define and manage configuration elements of an
application.
The configuration management of a Portal Application provides a model to:
• Define the configuration element of an application. A Portal Application defines its own
configuration containing any information that needs to be adapted to the environment to
customize the behavior of the Portal Application
• Load in the environment the definition of the configuration. The load of this configuration is
able to merge and upgrade already existing configuration elements.
• Manage (Create/Update/Delete) the configuration objects of the Portal Application. This is
achieved by a standard administration UI invoked by but this could also be done during the
load of the Portal Application by creating some default instances of the configuration.
• Read/Write/Update/Delete via an API, those configurations objects and react to changes
occurring of those objects.
For more information please see: http://help.sap.com/portals/ or refer to the document on meta-data
from the Configuration Framework.
The following points will be covered in this chapter:

• Create a config archive
• Package the config archive with the PAR Export Tool
• Accessing the data
• Config Framework API
• React to Configuration events
• Start the config mode.

Create a Config Archive
Place your configuration files in folders
• Data files: <project root>/config/data/<plugin name>

• Meta files: <project root>/config/meta/<plugin name>
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).
Use Export PAR File of the PAR IDE

The deployment unit of the configuration is called the Config Archive. It contains the configurables as
they were on the file system and it gathers all the config classes (meta data) in a Config Meta
Archive.
The Export PAR functionality of the PAR IDE, allows to build the Meta Config Archive and the Config
Archive transparently. The Config Archive will be copied in <root project>/dist/PORTAL-INF/config
folder as a consequence it will be packaged automatically in the PAR file and it will be deployed when
the PAR is uploaded by the PAR IDE.
In order to build the Config Archive (and its Config Meta Archive) properly, the Portal Application
needs to provide some information in a specific file called configArchive.properties placed at the
root of the config folder.

Config Archive properties file
The plugin will place automatically the default value If non-mandatory values are specified as shown in
the example below:
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 Properties Manifest Mandatory Default

ca.name CA-Name No Project name
ca.version CA-Version Yes
ca.dependencies CA-Dependencies No
ca.creation.time CA-Creation-Time No Time
ca.creation.date CA-Creation-Date No Date
ca.creation.user CA-Creation-User No User name
ca.creation.machine CA-Creation-Machine No Machine name
CMA Properties Manifest Mandatory Default
cma.name CMA-Name No Project name
cma.version CMA-Version Yes
cma.dependencies CMA-Dependencies No
The possible values are:

cma.storage CMA-Storage Yes • sfs
• pcd
cma.creation.time CMA-Creation-Time No Time
cma.creation.date CMA-Creation-Date No Date
cma.creation.user CMA-Creation-User No User name
cma.creation.machine CMA-Creation-Machine No Machine name

Access data
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:
<property name="PrivateSharingReference
value="com.sap.portal.runtime.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>
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:
<property name="PrivateSharingReference"
value="com.sap.portal.runtime.config,
com.sap.portal.runtime.system.hooks"/>
Then the virtual Portal Component is created as an instance of the Config Component.

Note that in the example below the ConfigRootFolder is set as the subfolder font of the plugin
com.sap.portal.runtime.config.prototype.
<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>
Sharing Configuration between Applications

If the Root-Plugin name is not the same as the application name then the ConfigRootFolder has to
match the Root-Plugin (see also).
This is the mechanism used to have different Portal Applications sharing the same configuration.
Use the Config Framework API

• Get the Configuration Service
IConfigurationService service = Configuration.getInstance();
• Get the Config Manager

IConfigManager manager =
service.getConfigManager(IConfigClientContext.createContext());
• Get the Config Plugin

IConfigPlugin plugin =
manager.getConfigPlugin("/com.sap.portal.prt.config.prototype");
The path /com.sap.portal.prt.config.prototype matches the Root-Plugin name.
• Get the Configurable

IConfigurable configurable = plugin.getConfigurable("hello_text");
• Get the Property Value

String text = configurable.getPropertyValue("value");

Configuration Event Subscription
Implement the interface IConfigEventListener

If a Portal Application wants to be notified about modifications on its configuration, this application has
to implement the interface IConfigEventListener.
public class HelloWorld extends AbstractPortalComponent implements

IConfigEventListener {
...
}
Add the required methods

Two methods have to be implemented:
• public String getConfigListenerId(): return the ID of your listener
public String getConfigListenerId() {

return "com.sap.portal.prt.config.prototype.HelloWorld";
}
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
public void configEvent(ConfigEvent event) {

if (event.getType() == ConfigEvent.CONFIGURABLE_ADDED) {
...
}
else if (event.getType() == ConfigEvent.CONFIGURABLE_UPDATED) {
...
}
else if (...
}
List of events type:

• CONFIGMANAGER_INITIALIZED: A configmanager has been initialized.
• CONFIGMANAGER_TERMINATED: A configmanager has been terminated.
• CONFIGURABLE_ADDED: A new configurable has been added.
• CONFIGURABLE_DELETED: A configurable has been deleted.
• CONFIGURABLE_LOADED: A new configurable has been loaded from store.
• CONFIGURABLE_UPDATED: A configurable has been updated.
• CONFIGURATION_UPDATED: The configuration has been updated (by a queued update).

Add a listener
To be notified about changes on the configuration data, the Portal Application has to subscribe to the
IconfigEventService and by specifying domains for which the application wants to receive notifications.
Specifying domains allows the Configuration Framework to perform a preliminary filtering on the events that will
be sent to the listener. In that case, the listener receives only the events that are relevant the application.
try {
// get Configuration Service
IConfigurationService configurationService = Configuration.getInstance();
IConfigEventService eventService =
configurationService.getConfigEventServiceInstance();
// add listener on domain

String[] domains = {"/com.sap.portal.prt.config"};
eventService.addConfigEventListener(this, domains);
}
catch (InitialConfigException e) {
}
catch (InvalidEntryException e) {
}
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) {
}
catch (InitialConfigException e) {
}
Start the Config Mode

The configuration of a Portal Component can be displayed by executing the component in config mode. This is
achieved as any other mode by adding /prtmode/config/ at the end of the prtroot URL. The system configuration
delegue will open the Config Framework UI. The UI display the configuration starting at the root folder of the
component.
Configuration of Portal Service can be displayed by creating a virtual component as described above.
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
Always pass the original exception
Issue Example (negative)/ Explanation

Always pass catch (IOException e)
the original
{
exception on
throw new RuntimeException("Problem in I/O.");
}
By not doing this, the original problem might be hidden. The original exception can be
passed on by adding them to the message ("message: " + e). Better is to use a
constructor which can take an exception as argument as well, e.g.
new PortalRuntimeException("Error in I/O.", e)
Always include a message

Always include throw new IOException();
a message
There is always additional information which is useful to the user. If possible this
information should be constructed dynamically. However, this should not introduce
problems. Following example produces a NullPointerException if context is null:
throw new RuntimeException("Error in "+ context.getComponent());
Do not make wrong assumptions

Do not make catch (NamingException e)
wrong {
assumptions throw new PortalRuntimeException("Registry not found:" + e);
}
There are many subclasses of NamingException and the reason might be another.
Page 73 /113
Do not have empty exception handlers

Do not have catch (Exception e)
empty
{
exception
handlers // ignore
}
This interrupts the exception flow without doing something, thus hiding a problem.
Nobody can find the problem caused by an exception handled this way. The
exception caught might be a subclass of the specified one, thus presenting another
problem than expected.
Assuming somebody needs to find such a problem at the customer site, it might take
hours to search and then one ends up in an empty exception handler. If there is really
a need for an empty exception handler there should be a good reason which should
be commented and the exception should be logged.
Do not only print the stack trace

Do not only catch (NamingException e)
print the stack
{
trace
}
If stdout is not redirected, the exception is only visible on the console. The console
however might not always be there or accessible, e.g. the application was started
using javaw which does not open a console. In addition there is sometimes to much
output on the console thus making it impossible to follow the output. The exception
should be logged.
Log Important Exception

Log important catch (IOException e)
Exception {
throw new RuntimeException ("Exception while reading service
parameters: " + e);
}
In general, when important information is lost in an exception handler because it is not
passed on it should be logged. The following line logs the stack trace of the exception
above:
PortalRuntime.getLogger().severe(e, " Exception while reading
service parameters.");
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.
In both cases the upload proceeds in two steps:

• It uploads the PAR file into the Application Repository
• It notifies all PRT nodes that a new Version of the application is available
Uploading a PAR File to the Application Repository

The PAR file is stored in the application repository. It is important to understand that there is only one
Application Repository and all PRT nodes of the SAP J2EE cluster are sharing the same content. It means
that the Upload procedure is to be done only once.
Basically this the PAR Upload procedure stores the whole archive in the underlying persistence layer (ie: a
DataBase). It also extracts from the deployment descriptor (portalapp.xml) all information requiring fast access
at runtime.
Deploying a PAR File on all PRT Nodes

Once the Upload to the Application Repository is completed, the upload process notifies all PRT nodes in order
to guarantee that all nodes will take care of the latest changes.
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.
Local Deployment Consistency

The upload process updates all PRT nodes. This procedure of course can’t succeed when the server is down.
To solve that problem, PRT also checks the local deployment before loading the application into the memory.
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.
Principle and approach

The approach used by the Portal Runtime to support internationalized application is based on the choice to use
the Unicode character set to take advantage of the Java’s internationalization capabilities in the following 3
areas of a Portal Application.
• How data is passed to the Portal Application by the browser.
• Manipulated those data in the Java/JSP code of the Portal Component.
• How data is presented to the user.
Internationalization is the process of designing or converting an existing program so it is capable of being used
in more than one locale. A locale defines a set of culturally-specific conventions for the display, format, and
collation of data. In Java, a Locale object specifies a locale, which is simply a container for strings identifying a
particular language and country.
The first part of the internationalizing process is the resourcing. It involves isolating the locale-specific resources
of the source code into modules called ResourceBundle. Those modules can then be independently added to or
removed from the application. For a Portal Application, all the locale-specific strings and objects are stored in a
set of ResourceBundle packaged with the PAR file.
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.
Resource Bundle Name

The name of the resource bundle is defined by the property ResourceBundleName of the Profile of the Portal
Component.
The rules to find the resource bundle are the rules defined by the Java language. For example, if the current
default locale is en_US, the locale of the component is fr_CH, and the resource bundle name is localization,
resource bundle lookup will search for the following classes, in order:
• localization _fr_CH
• localization _fr
• localization _en_US
• localization _en
• localization
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)
Resource Bundle packaging

The Java implementation is excepting the resource bundles to be accessible by the Java Class loading
mechanisms. So, the localization properties must be packaged in a folder of the PAR file accessible by the Java
Class Loader. For example, it could a JAR file in PORTAL-INF/private/lib or just a single file in the PORTAL-
INF/private/classes directory.
<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;
public class HelloWorldComponent extends AbstractPortalComponent {
public void doContent(IPortalComponentRequest request,

IPortalComponentResponse response)
{
java.util.ResourceBundle resource = request.getResourceBundle();
response.write(resource.getString("GREETING"));
}
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
Name Description Default value

runtime.doubleByteSupport Convert data sent by the browser true
runtime.doubleByteSupport.encoding Encoding used to convert the data UTF-8
received from the browser
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.
It relies on two concepts:

• Security Zone : A catalog containing a set of Portal Components and Portal Services, on which ACLs
are attached and checked at runtime when accessing to the Portal Object belonging to a zone.
Examples:
Security Zone Description

com.sap.portal.runtime Zone containing all PRT system components
like ErrorComponent, ConfigComponent
• Safety Level : A security level in a zone. It allows to group objects belonging to a zone into different
categories.
Examples:
Safety Level Description

HIGH_SAFETY Administrator rights are required to access
objects belonging to this zone
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:
Safety Level Description

HIGH_SAFETY Administrator rights are required to access to a
zone. e. g. has to be member of the
system_admin role
MEDIUM_SAFETY User has to have certain roles in the system to
enter the zone. e.g. content_admin for portal
applications
LOW_SAFETY User needs to be authenticated, to enter the
zone.
NO_SAFETY Anonymous access is allowed
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.
Example of portalapp.xml containing the definition of a zone for a Portal Component.
<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 namespace of the business application is defined as follows:
Business Application Namespace

Portal applications com.sap.portal
User Management com.spa.ume
KM com.sap.km
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:
Object Purpose Examples

Application Applications are referenced by other CharingReference = ApplicationName,
applications to indicate class loader
PrivateSharingReference = ApplicationName
dependencies in the deployment descriptor
file (portalapp.xml). ServicesReference = ApplicationName
Application Application are referenced by either componts getResource(applicationName, ..)
or services to access to a resource packaged
in the PAR file of the application by calling
one of the different getResource() methods of
the API.
Service Services are referenced by components or getService(ServiceName)
services using the getService() API of the
PRT.
Service Services are referenced in a URL to access irj/servlet/prt/soap/ServiceName
WEB services using the soap connection.
Component Components are referenced by other getComponentContext(ComponentName) in
components using the getComponentContext the URL.
of the PortalComponentRequest object of the
PRT API.
Component Components are referenced in the URL to be irj/servlet/prt/portal/prtroot/ComponentName
executed and rendered.
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" >
The following name will be valid and recognized by the Portal:

• myApplication.myComponent, myAlias.myComponent for the component defined myComponent.
• myApplication.myService, alias.service for the service myService.
• myApplication or myAlias for the application myApplication.
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.
Local Deployment Overview

The directory structure after deploying the “irj.ear” file should look like below:
Important: Please note that this structure can be change at any time. The java code should not assume that the
structure will remain the same in the next release. The PRT API provides methods to abstract from the real
location of resources.
<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
Local Deployment of Portal Applications

A portal application is deployed locally either at startup or on first call (upon HTTP request). The PAR file
content is extracted and split into 2 parts.
- The public part contains Web resources (images, scripts, style sheets) that are to be accessible
from the user-agent (ie: the browser).
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.
Elements of a Portal Application

The following illustration gives an overview over the elements of Portal Applications from a resource
perspective.
Portal Application
Web Resources non-web resources
images, static data files, private JSPs, ...

style
sheets, code
web server scripts,
accesses static Referenced
html, private code use Portal
etc. (implementation) Application's
shared code
Shared code
(APIs)
Referencing
Portal
access to config, use Applications
application data,
personalization,
etc..
Hosting environment (PRT and more)

//
//
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
Class Loading in the Portal Runtime

The following illustration shows the class loading relations between Portal Applications.
The areas marked as "API" represents all the public resources of an application as far as related to class
loading. In the PAR format these are all the definitions in jar files under PORTAL-INF/lib and all files under
PORTAL-INF/classes. This may be JAVA class definition, but also Resource Bundles for example.
The area marked as "core" represents all the private resources of an application as far as class loading is
concerned. In the PAR format these are all the definitions in jar files under PORTAL-INF/private/lib and all files
under PORTAL-INF/private/classes.
by "SharingReference" (or
not if "5.0" policy in use ServicesReference for Arrow directions
compatibility) indicate
propagation of
Application Y
type definition
API knowledge by
class loading
Using Application
X
mechanism.
API
default (in EP6

and EP5)
public
by "PrivateSharingReference"
private
default (in EP6)
non-default
API
only if
"CoreAccessInAPI"
policy in use Core
Class Loading Examples

The following picture shows the difference between the PrivateSharingReference and the SharingReference
attribute:
• When setting the reference from B to C to private, A does not have any visibility on C.
• On the contrary, when the reference from B to C is not private, A gets visibility to C.
Page 90 /113
A B C
API API API
CORE CORE CORE
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.
<?xml version="1.0" encoding="iso-8859-1"?>
<application>
<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>
<property name="diplayStyle" value="list">
<property name="type" value="select[list,history]"/>
</property>
</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
The chatapi.jar should contain:
com/sap/portal/exampleapp/api/IChatService.class
and chatcore.jar:
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.
...

Context applicationContext = context.lookup(“MyAppName”);
The Central Configuration context relies on the JNDI API plus the IStreamSource interface. This interface is
used to read and write the data.
How to get the sub context that belongs to the application?

The application can get its own sub context calling the lookup method on the root context. Note that this context
doesn’t have to be created by the application; it exists by default and has been created during the PAR Upload.
...

Context myContext = context.lookup(“MyAppName”);
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 ;
}
Reading the data from the IStreamSource:

In our example, the source refers to a java property file (the application has to know it!). We can simply load the
data source using the IStreamSource.getInputStream method.
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.
Executing a Servlet as a Portal Component.

Any servlet can be packaged and executed as a Portal Component by packaging the servlet objects in a PAR
file as shown in the example below:
1. The ServletTest class defines as shown below a standard servlet.
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpServlet;
public class ServletTest extends HttpServlet

{
protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
try {
resp.getWriter ().write ("I am a servlet ");
}
catch (Exception e)
{
}
}
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>
3. The Servlet object should be packaged in the PAR.
<Portal Archive>
|
+-- META-INF
+-- MANIFEST.MF
+-- …
+-- PORTAL-INF
| |
| +-- private
| | +-- lib
| | +-- servletTest.jar
Accessing to the Portal Service from a J2EE object.
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.
JNDI Service Providers

Any portal application that want to play the game will have to register its own JNDI Service provider under a
name space (the scheme). This JNDI provider does not just serve the PRT, but everything running in and
(potentially) next to the PRT.
The contract between the content provider and PRT is the following:
- The JNDI provider must be able to provide objects implementing the IPropertyContentProvider
and IPropertyContent interfaces.
- The IPropertyContent implementation must provide at least the CodeLink property. This property is
used to get the corresponding PAR File (and therefore the implementation) from the application
repository
For further detail concerning JNDI Providers please have a look to: PRTJndiSupport page 42.
Starting Portal Objects

When PRT receives an HTTP request, the prtroot URL parameter specifies the unique name of the object that
is to be started. This name here is a JNDI name and the syntax used is not PRT-Specific. To get the object PRT
simply calls the lookup method on an Initial JNDI Context.
Object o = null ;
try {
o = initialContext.lookup(prtroot);
}
catch ( Exception e ) { }
if ( o!=null && o instanceof IPropertyContentProvider ) {

provider = (IPropertyContentProvider)o;
}
else {
throw new PortalRuntimeException("Portal object not found: "+prtroot );
}
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.
This configuration is done by using the two following properties.

• HelpURL
• HelpName
Property Name Description Examples

HelpURL gives the location of the help text to docs/help.html
display when the Portal Runtime
docs/myhelp/index.html
renders a Portal Component in the
Help Mode. http://www.sap.com/help/ip.html
Many formats are supported. /com.sap.par.help.default/docs/index.html
HelpName Gives the name of the help text file Index.html
that needs to be located in a
subfolder of the help public folder of
the PAR.
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.
HelpURL Portal Component property example.
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.
HelpName Portal Component property behavior
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.
public class MyAbstractPortalComponent

extends AbstractPortalComponent implements ITestable
{
public String getTestName ()
{
return "MyAbstractPortalComponent";
}
}
Each test methods invoked by the Test Mode execution, are written against the following pattern:
public void testXXX (IPortalComponentRequest aRequest,

IPortalComponentTestResponse aResponse);
The IPortalComponentTestResponse is an IPortalComponentResponse enriched with the following test

methods
• log(String mgLog, String msgId) logs a message in the output of the Portal Component
• assert (boolean condition, String msgLog, String msgId) stops the execution of the test when the
test condition fails by outputting a message in the test output.
The Portal Component is invoked in test mode by using the following URL:
• /irj/servlet/prt/portal/prtroot/<MyComponent>/prtmode/testComponents/testRendering/html
Page 100 /113

Logger configuration
Every logger accessed by the Portal Logging API are defined in the following files:
• Logger.xml in the WEB-INF\portal\system\xml directory. It contains Internal Portal Runtime
loggers like the default logger.
• Logger.xml in the PORTAL-INF/logger folder of the PAR file. Each Portal Application can define
its own logger by packaging a logger configuration file in its PAR as described in the following example:
<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>
Page 101 /113

JSP Support
The objective of this chapter is to describe how application developers can integrate and use JSP technology
into a Portal Component.
The Portal Runtime supports two ways to use JSPs in the Portal:
• Declarative way: the JSP lives in the portal as a component on it's own.
• Programmatic way: any Portal Component can access any JSP brought with its PAR file or that belongs
to another Portal Component.
Declaring JSP as Portal Component

Two properties in the profile of the Portal Component indicate that a JSP needs to be compiled into a Portal
Component.
Property Value Description

JSP path/FileName Relative path to the JSP in
component resource
ComponentType jspnative Tells the PRT that this component
is based on a JSP
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"
JSP selected programmatically

The JSP file is selected programmatically into the code of the Portal Component by including it as a resource in
the response:
The first example below shows how to access to a JSP file packaged into the caller Portal Component.
public class CheckBoxComponent extends AbstractPortalComponent

{
public void doContent(IPortalComponentRequest request,IPortalComponentResponse
response) {
response.write("calling pagelet checkresult.jsp");
IResource jspResource = request.getResource("jsp", "jsp/checkresult.jsp");
response.include(request, jspResource);
}
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.
public class CheckBoxComponent extends AbstractPortalComponent

{
public void doContent(IPortalComponentRequest request,IPortalComponentResponse
response) {
response.write("calling pagelet checkresult.jsp");
IResource jspResource = request.getResource("JSPValidation", "jsp",
"/jsp/include/foo.jsp");
response.include(request, jspResource);
}
In that case, the PRT will find a JSP called foo under the directory jsp in the component JSPValidation.
Page 102 /113

JSP packaging/Compilation
The JSP must be located in the par file under the private section in any directory:
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.
Class Loader consideration

When accessing a JSP file, the Class Loading separation philosophy of Portal Runtime is preserved.
During compilation, the class path used by the Java compiler is build with the JARs file and class files
accessible from the class loader that have been used to create the Portal Component using the JSP file.
In order to compile the generated JSP pages at run-time, PRT needs to locate the tools.jar of the JDK. The
tools.jar must be set in the class path of the WEB server environment. By default this jar is retrieved with the
system property java.home defines by JDK. If It's not retrieved a property "jsp.addclasspath" in the file
"prtDefault.properties" can be used to define where to find the tools.jar file which are not retrieved by the class
loader.
#
# 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.
Supported Features in the PRT

Implicit Objects
The JSP standard implicit objects accessible via scripting in the JSP are also accessible in a compiled Portal
Component.
Objects Description Type
request original request object javax.servlet.ServletRequest
com.sapportals.portal.prt.IPortalComp
response portal component response
onentResponse
javax.servlet.jsp.PageContext (not all
pageContext the page context for this JSP page
functionnality are supported)
com.sapportals.portal.prt.IPortalComp
component request the portal component request
onentRequest
the session object created for the javax.servlet.http.HttpSession (specific
session
requesting client implementation)
Page 103 /113

application the servlet context obtained from the javax.servlet.ServletContext
servlet configuration object
out an object that writes into the output stream javax.servlet.jsp.JspWriter
config the servlet config for this JSP page javax.servlet.ServletConfig
page the instance of this page's implementation com.sapportals.portal.prt.IportalCompo
class processing the current request. nentContext
the JSP standard implementation is
returning the servlet. The PRT returns the
Portal Component Context of the
Component that is associated to the JSP
pages.
exception the uncaught java.lang.Throwable that java.lang.Throwable
resulted in the error page being invoked
Page directive
The page directive accepts the following parameter:
<%@page page_directive_attr_list %>

page_directive_attr_list ::={language="scriptingLanguage "}
{extends="className "}
{import="importList "}
{session="true|false "}
{buffer="none|size kb "}
{autoFlush="true|false "}
{isThreadSafe="true|false "}
{info="info_text "}
{errorPage="error_url "}
{isErrorPage="true|false "}
{contentType="ctinfo "}
{pageEncoding="peinfo "}
The following table shows the actual support of the page directive in the Portal Runtime:
Directive Description Support

language scripting language used in scriptlets java
fully qualified class name of superclass of the class name, must be accessible
extends
class to which the JSP Page is transformed by the Portal Component
java types describing the types that are available class name, must be accessible
import
to the scripting environment by the Portal Component
indicates if the page requires participation in a
session supported
Session
Specifing the buffering model for the initial out supported.

buffer
JspWriter to handle content output from the page
Specifing if the buffered output should be flushed

autoFlush supported
automatically
Indicates the level of thread safety implemented in
isThreadSafe not supported, always multithread
the page.
Page 104 /113

Defines an arbitrary string that is incorporated into
info not supported
the translated page
indicate the current JSP page is intended to be the
supported (See Portal Runtime
isErrorPage URL target of another JSP's page. if true the
extension)
implicit variable exception is defined
Defines an URL resource to which any Java
Supported (See Portal Runtime
errorPage Programming uncaught Exception will be
extension)
forwarded
Defines the character encoding for the JSP page
contentType Supported
and for the response of the JSP page
Defines the character encoding for the JSP page.
pageEncoding Supported
This is used to know in which
Portal Runtime extension

The following chapter describes the extension implemented by the Portal Runtime.
ErrorPage Attribute
The attribute errorPage is changed to add more flexibility for referencing a Portal Component that can handle
and display an error in a Portal page.
The following table shows the different supported value of the [page] value for the errorPage attribute
<%@ page errorPage="[page]" autoflush="false" %>
[page] Directory Description

.../.../errorpage.jsp private folders Redirects to the JSP relatively
to the current JSP if error
prt:component:MyComponent.default private folders Redirects the given component
if error
prt:component:MyComponent.SubComponent private folders Redirects the given component
if error
prt:componentres:MyComponent.default,/test/anot private folders Redirects to the JSP that
her/j1.jsp belongs to given component
include directive/action
The include directive is used to include text and/or code at JSP page translation time.
directive/action description Supported

<jsp:include page="[path]" /> content is not parsed; it is included at the Supported
runtime
<%@ include file="[path]" %> content is parsed by the JSP container Supported.
The following values are accepted by the Portal Runtime:

[path] Directory Description
.../.../custom.jsp same as current JSP Includes the JSP relatively to the
Page 105 /113

current JSP (belongs to the current
component)
prt:componentres:MyComponent.default private folders Includes the JSP that belongs to given
,/test/another/j1.jsp component
The include action is used for the inclusion of static and dynamic resources in the same context as the current
page.
[path] Directory Description

.../.../custom.jsp private folders includes the jsp relatively to the current
JSP
prt:component:MyComponent.default private folders includes the given component
prt:component:MyComponent.SubCompo private folders includes the given component
nent
prt:componentres:MyComponent.default,/ private folders Includes the JSP that belongs to given
test/another/j1.jsp component
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.
Tag lib packaging

All Java Server Pages that are compiled into a Portal Component can use custom tags lib by following the rules
described below:
The class file that implements the tag lib definition must be packaged in the lib or classes directory of the
Portal Component PAR file.
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="[uri]" prefix="custom" %>
[uri] Directory Description Profile

.../.../custom.tld same as takes the tag library definition file none
current JSP relatively to the current JSP
prt:taglib:custom private folders the tag library is referenced by an custom=/taglib/custom.tld
identifier which must be defined in the
profile of the component. The id here
is custom. If the JSP page is include
in a component as a resource, the tag
library must be defined in the profile
of the component.
Page 106 /113

Using the taglib provided by Portal Services
All Java Server Pages that are compiled into a Portal Component can use tags libraries provided by Portal
service by following the rules described below:
The Tag Lib Definition file must be referenced into the Portal Component Profile as follow:
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.
<jsp:useBean id="name "scope="page|request|session|application" typeSpec >

body
</jsp:useBean>
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:
<jsp:useBean id="foo" scope="page" class="beans.checkbox.CheckTest" />
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.
Page 107 /113

Handling Request Events
Request Event must be generated by the standard Portal Component API method used to create event. Those
events are then generated in the content of the Portal Component and the methods to handle the events have to
be written in the Portal Component. Here is an example of possible use of Portal Component Evens in JSP
page.
<% logger.setComponentRequest(componentRequest);
IPortalRequestEventData data = componentRequest.createRequestEventData();
IPortalRequestEvent loEvent = componentRequest.createRequestEvent("oneEvent",data);
%>

<FORM type=POST ACTION= <%=
componentRequest.createComponentURL(componentRequest.getNode(), loEvent)%> >
<br/>
Page 108 /113

Asynchronous Response API
PRT provides an internal API to make the programming of gluer components more powerful. This API is only
available from the core (package com.sapportals.portal.prt.core.async).
This API provides two features:
- Multithreaded rendering to speed up the rendering (managed by a thread pool)
- Timeout for components, if the component takes too long to render (given a timeout value) 3
scenarios are possible:
- Either a valid cache content is available for the component, in that case this cache will be used
and the component won’t be rendered.
- Either the component has no cache content, in that case the component won’t be rendered and
a timeout message can be displayed.
- Either the component has an obsolete cache content available: in that case this obsolete cache
content will be displayed but the component will be rendered as well and the cache will be
updated with the new content outside the request cycle.
A component can use a special asynchronous response that provides some methods to include nodes
asynchronously (asyncInclude method in interface IAsyncPortalComponentResponse).This method returns
immediately. Thus a method to wait for the end of all the nodes rendering has been implemented in the
asynchronous portal component response (method waitForAllIncludesDone ())
The component can be notified (IAsyncResponseListener) when the content for the included node is available
with the status of the inclusion of the node (See AsyncIncludeStatus)
Configuring the thread pool size

The file prtDefault.properties contains a special entry to configure the rendering thread pool size.
(async.response.pool.size). The default value is set to 100. If the thread pool has no more threads available
then the rendering will be done in the current thread.
Another entry also specifies the timeout thread pool size (it should roughly corresponds to the rendering thread
pool size). The entry is async.response.timer.pool.size and is also set to 100 by default. Is there is no more
threads available in the timer thread pool, the timeout feature is disabled for the component .
Configuring the timeout

The default timeout value for component is also defined in the prtDefault.properties (10000ms). This value can
be customized for each component in the profile using the property timeout.
Example of a component declaring a timeout of 2 seconds in its portalapp.xml
…
<components>
<component name="MyComponent">
<component-config>
<property name="ClassName" value="com.sapportals.portal.MyClass"/>
</component-config>
<component-profile>
<property name="timeout" value="2000"/>
</component>
</components>
…
It is also possible to supply a timeout value in the AsyncPortalComponentResponse constructor :
Page 109 /113

public AsyncPortalComponentResponse (IPortalComponentRequest request,
IPortalComponentResponse parent, long timeout)
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)
public void doContent (IPortalComponentRequest req, IPortalComponentResponse r)

{
IAsyncPortalComponentResponse resp= new AsyncPortalComponentResponse (req, r);
…
resp.asyncInclude (request, node1, this)
resp.waitForAllIncludesDone ();
// Simply writes all the content to the parent response
resp.writeToParentResponse ()
}
Page 110 /113

Here is a schema that shows how the rendering is done throw the time:
Time
resp.asyncInclude (node1)
Main thread
Check for Node1 Cache Content: Not up to date, launch a rendering thread
Check for Node2 Cache Content: Not available, launch a rendering thread
Thread 1
Check for Node3 Cache Content:
Thread 2 available and valid, return cache
content
resp.waitUntilAllIncludesDone ()
doContent (req, resp)

Regular Request cycle {
getDatabaseValues ();
}
doContent (req, resp)

{
getContent ();
timeout node1 Node1 : Returns old CacheContent

Returns to browser waitUntilAllIncludesDone () returns :
Content is available for node1, node2 and node3
timeout node2 Node2 : do nothing because the rendering is already finished
Outside Request cycle
Updated cache Content for node 1
Page 111 /113

Index
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
Page 112 /113

Portal Object Model 34 S
Portal Registry 30
Safety Level 83
Portal Service 12, 21
SAP J2EE 9
portalapp.xml See Deployment Descriptor
Security Zone 83
PORTAL-INF 14
Service
PrivateSharingReference 17
Service Configuration 22
Property
Service Profile 22
ClassLoaderPolicy 56
Servlet
ClassName 18
Component Type 96
ComponentType 102
SharingReference 16
DeploymentPolicy 56
SOAP 48
PrivateSharingReference 17
SharingReference 16 T
PRT bridge 9
prtroot 97 Tool
LogViewer 75
R tools.jar 103
Request Cycle 34 U
Resource Bundle 80
Upload 77
Resources
Non-Web Resources 14 URL parameter
Web Resources 14 prtroot 97
revision number 78 W
RFC Engine 63
WEB Services 46
WSDL 47
Page 113 /113

Prtguide 60

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Prtguide 60

Uploaded by

Copyright:

Available Formats

Portal Runtime –

Introduction and Positioning

Portal Runtime Technology Page 6 /113

Portal Application Archive (PAR files)

Portal Component Profile

Portal Component Config

Portal Runtime Mode

Portal Object Model (P.O.M.)

Portal Runtime Technology Page 7 /113

Portal Runtime Technology Page 8 /113

SAP J2EE Application Server

SAP J2EE Services

PRT Bridge Service

Portal Runtime Technology Page 9 /113

Application name Description

Portal Runtime Technology Page 10 /113

API ELEMENTS JAVA NAME DESCRIPTION

Portal Runtime Technology Page 11 /113

Portal Runtime Technology Page 12 /113

Portal Runtime Technology Page 13 /113

PAR File format

Portal Runtime Technology Page 14 /113

Portal Runtime Technology Page 15 /113

Application-config see Application Configuration Properties

<?xml version="1.0" encoding="iso-8859-1"?>#

Portal Application Configuration

<property name="myProperty" value="myPropertyValue"/>

The following table describes currently meaningful application configuration properties:

Name Description Admissible value Default

Portal Runtime Technology Page 16 /113

Name Description Amissable Values Default

Portal Runtime Technology Page 17 /113

Name Description Mandatory

Portal Component Configuration

Name Description Mandatory Default

Portal Runtime Technology Page 18 /113

Portal Component Profiles

Name Description Possible values Default

Portal Runtime Technology Page 19 /113

2: This level includes all EPCF features that

3: This level includes all features of level 1

If two or more embedded iViews with different

<property name="Color" value="red">

Name Description Admissible value Default

Portal Runtime Technology Page 20 /113

no-dialog: per-user storage,

dialog: per-user storage and

Name Description Mandatory

Portal Runtime Technology Page 21 /113

Properties of reserved meaning are:

startup If set to "true", the service will be started at No false

Portal Service Profiles

Portal Runtime Technology Page 22 /113

PAR Upload Application Repository / Database

Local Deployment / File system

Application Broker Object

Portal Runtime Technology Page 23 /113

Portal Runtime Technology Page 24 /113

Request Portal Portal Registry Portal Portal

Portal Runtime core Cache

Portal Application Repository

Property Description Default value

dispatcher.portal.system.properties the portal properties system/properties/workplace.proper