In the portal architecture, the portal never talks to a portlet directly. It uses an interface to an entity called a provider that represents and manages the portlets. A provider is an entity that owns portlets. Oracle9iAS Portal uses the provider to "provide" all the information for owned portlets and to drive portlet operations. The provider is the communication link between the Oracle9iAS Portal and portlets.
There are two main types of provider interface - Database and Web. When registering a provider, you select either "Database" or "Web" as the Implementation Style.
Oracle9iAS Portal communicates with the provider for various reasons like registration, getting information about the portlets, establishing sessions, getting the portlet content and so on. This article describes how Oracle9iAS Portal allows the provider to perform special processing, such as establishing or tracking sessions before a portlet is executed and how cookies are handled by Oracle Portal.
The article starts with an overview of Oracle Portal architecture. The following sections cover the impact of provider registration on session management, cookie management by Oracle Portal and synchronization of portal / provider session. The final section includes FAQs related to Oracle Portal session management.
Oracle9iAS Portal Architecture
This section describes the high level architecture of Portal Repository and the process flow involved when the page request comes to the Portal Repository.
When a request is received for a page, the Parallel Page Engine in the middle tier retrieves the meta-data by making a request to the Portal Repository. The Parallel Page Engine is a Java Servlet in the middle tier that takes a proprietary set of meta-data, and processes it to create a Portal page. The meta-data is the page definition that contains all of the information that will be needed to retrieve the individual portlets for the page along with the actual layout of the page as it will appear in the browser.
As part of the meta-data generation, Oracle9iAS Portal contacts all the providers that contribute portlets in the page if they specify during registration that they get called for some special processing. This is the call that allows providers to do processing based on the user session, log the user in the provider's application if needed and establish provider sessions in Oracle Portal. For Database providers this call is referred to as 'do_login' and for Web providers it is called 'initSession'. Since most Web enabled applications track sessions using 'cookies', this API call allows the provider of application to return cookies.
Oracle Portal sends the cookies received from the providers along with the page layout information. These cookies will be used by the Parallel Page Engine when it makes show/render requests to the providers. Portlet content from providers during this call is sent back to the Parallel Page Engine which constructs the completed page which is finally presented to the browser.
Session Related Information During Registration
Registration of providers is the first step in the integration of a provider in a given Portal. When the providers are registered using the provider registration API or the provider registry UI, information about the providers including session handling details are obtained. The fields that impact how the Oracle Portal handles sessions are explained below.
Provider Registration API
The API register_provider(p_provider in provider_record) in wwpro_api_provider
package is used for provider registration.
The fields in the provider record that impact session handling are:
login_frequency:
Login_frequency is the invocation frequency of the do_login/initSession call to the providers. The valid values are:
LOGIN_FREQUENCY_ALWAYS('A')
The call to provider's do_login/initSession() is made every time the portlet is rendered on a page even if the user session is the same. Note: Due to performance reasons providers are recommended not to use this option unless it is really necessary. The middle tier contacts the database for login call before rendering the portlet and with this option it needs to do it every time the portlet is rendered.LOGIN_FREQUENCY_NEVER('N')
The call to provider's do_login/initSession() is not made before the portlet is rendered in a page.LOGIN_FREQUENCY_ONCE('O')
The call to provider's do_login/initSession is made only the first time the portlet is rendered in a page in a given session. If there is change in session due to the login status of the user or the language, then the call is made again. For example, if the user is not logged in and accesses a page, the session created will be a public session and the do_login/initSession will be called for portlets in that page that require the call. For subsequent requests to view the same page, the do_login/initSession will not be made. If the user logs in, then the session will be updated from a public to an user session in which case the do_login/initSession call will be made the first time. If the user logs out again, the session will become a public session resulting in a do_login/initSession call to the providers.LOGIN_FREQUENCY_PUBLIC('P')
Choosing this option indicates that the provider is a Public provider. For Web providers, the name of the user that is sent is always 'PUBLIC' if the provider chooses this option. The providers will not receive any session related information like the session id, the time that the user logged in, even if they set the require_session_data flag to 'true'. This flag is explained in the following section. This also means that the call to the provider for allowing them to do session/login based processing will not be made. For example, if the provider is supplying a News portlets or any portlet that is not sensitive to the user that is logged on, then the provider may choose this option. For database providers, since the user/session related information is always available through context APIs, choosing this option will impact only the do_login call. The do_login call will not be made and is equivalent to choosing a login frequency of 'NEVER'.same_cookie_domain:
This field allows the providers to indicate whether the scope of the cookie that they create falls within the same domain as that of Oracle Portal. This is applicable only to Web providers. Applications uses cookies to store information on the client's side usually for keeping track of sessions. Oracle Portal allows providers to return application cookies or any cookies that they may create and these cookies are made available to the providers in subsequent requests for show()/render() calls.
The domain attribute of a cookie specifies the domain name of the hosts that the cookie is valid for. The cookies are usually scoped using this attribute along with the path attribute when they are sent to the client, so that the client's Web browser sends them only to the hosts that are within the cookie domain when the requests are made.
For example, the provider is on 'myserver.mydomain.com', Oracle Portal is on 'myportal.mydomain.com'. Any cookies generated during the initSession() call will be forwarded to the browser by the portal as long as the cookies are scoped with a domain attribute '.mydomain.com'.When the browser sends a requests to a provider that contains the domain name '.mydomain.com' these cookies will be sent. Providers that want to share the same session as the application that is integrated into the portal by that provider should ensure that the same cookie domain setting is on. For more details on how to share sessions, refer to the section 'Session Sharing'.
The portal management of cookies for the providers that are on a different cookie domain as the portal is slightly different from those that are on the same domain. The cookies generated by a provider on a different domain will not be established at the Web browser since the portal that forwards the cookies is not on the same domain. For this reason, these cookies are stored inside the portal's session store and are made available in the subsequent requests to the Providers.
require_session_data:
This field allows the providers to indicate whether or not they want to receive portal session information for the logged on user. For example, portal session ID and the time that the user logged in to the portal. If the flag is set to true and the provider is registered as a 'Public' Provider by choosing LOGIN_FREQUENCY_PUBLIC, then this information will not be sent. In other words, this flag does not apply to Public providers.
Note: This flag has impact on caching if you are using it for caching portlet content. The Oracle Portal cache uses the URL of the portlet and since this information is added onto the URL, there will be multiple cache entries for the same portlet resulting in a lower cache hit ratio.
Provider Registration Screen
The registration screen consists of the following sections.
User/Session information:
The providers can choose from one of the two options depending on the session related information that they want to receive from Oracle Portal.
- User:
The name of the Oracle Portal user is sent to the providers if this option is chosen.
Login Frequency:
The providers can also specify how often the do_login/initSession call is to be made. The three choices available for Login Frequency are 'ALWAYS', 'ONCE PER USER SESSION' and 'NEVER'. These options correspond to LOGIN_FREQUENCY_ALWAYS, LOGIN_FREQUENCY_ONCE and LOGIN_FREQUENCY_NEVER in the provider registration API. Please refer to the provider registration API section for details.Require session Information:
The providers can use the check box under Login frequency to indicate whether or not they want to receive session information for the user. The session information consists of the Portal session ID and the time that the user logged on to Oracle Portal.
- Public:
Choosing this option is equivalent to LOGIN_FREQUENCY_PUBLIC in the Provider registration API. Please refer to the Provider registration API section for details.Web Providers - Same Cookie Domain
In the section for Web providers there is a provider URL field for entering the URL of the machine where the Web provider resides. There is a check box beneath the provider URL field that allows the providers to specify information relating to the scope of the cookie domain with respect to the portal. The prompt is "Web Provider in same cookie domain as the portal". This setting indicates that the provider is in the same cookie domain as the portal and as such should receive all the cookies that the portal received from the browser. This corresponds to the same_cookie_domain field in the provider registration API. Please refer to the provider registration API section for details.
Provider Configuration Options
The table below lists some questions that should help providers to choose appropriate
options during registration. Only the options that have impact on portal/provider
session management are listed here.
| Questions | Require Session
information |
Same
Cookie Domain (Applicable only to Web Providers) |
Login Frequency
or 'PUBLIC' |
| Does your provider (Database or Web) initialize session and create cookies the first time the portlet is executed in a page and use the cookies sent in the subsequent requests? | Yes or No | Yes or No | ONCE |
| Does your provider (Database or Web) initialize session and require portal session information like the Portal Session ID to create the session? | Yes | Yes or No | ONCE or
ALWAYS |
| Does your provider (Database or Web) initialize or update the session for the application every time the portlet is executed. For example a shopping cart application or user tracking application? | Yes or No | Yes or No | ALWAYS |
| Does your provider (Database or Web) provide public content that is not sensitive to the user that is logged in? | N/A | N/A | PUBLIC* |
| Does your Web provider require the portal session information just for identifying the provider session or any information stored on the provider side? | Yes** | Yes or No | NEVER |
| Do you want the cookies created by your Web provider to be stored in the client browser? | Yes or No | Yes *** | ONCE or
ALWAYS |
* - Choosing the 'PUBLIC' option is same
as choosing Login frequency 'NEVER' in case of database providers.
** - Applicable only to Web Providers since the database
providers have this information available.
*** - Applicable only to Web Providers since the database providers
within the Portal Repository share the same cookie domain.
Cookie Management by Oracle9iAS Portal
This section describes the
specification for the cookies generated by the provider and how
Oracle9iAS Portal manages these cookies.
Specification for Provider cookies
The cookies returned from the provider are either forwarded to the Web browser
or stored in the portal session store depending on the cookie domain of the
Provider machine and how the 'same cookie domain' field is set during Provider
registration. Since the portal acts as a client in sending cookies to
providers in it's requests there are some specifications on how the cookies
should be created by Providers.
Cookie Name:
The name of the cookie must be an HTTP/1.1 token. Tokens are strings that contain none of the special characters listed in RFC 2068 (Alphanumeric strings qualify as tokens). In addition, names that start with the dollar-sign character ("$") are reserved by RFC 2109.
Cookie Value:
The value of the cookie can be any string without white space or any of these characters:
[ ] ( ) = , " / ? @ : ;
If there is a need to place such data in the name or value, some encoding method such as URL style %XX encoding is recommended, though no encoding is defined or required.
Cookie Expires:
The expires attribute should be specified as a date string. The date string should be formatted as specified in the Netscape cookie spec which is:
Wdy, DD-Mon-YYYY HH:MM:SS GMT
Cookie Domain, Path:
The scoping rules of the cookies as specified in the domain, path attributes will not be applied for the cookies handled by the portal.
Provider cookie management
As explained in the architecture section, when the page is rendered calls to provider's initSession() and render() are made. The initSession() call originates from the Oracle9iAS Portal database and the render() call originates from the Parallel Page Engine. Cookies are sent in both the requests to the providers and the portal receives cookies in the initSession() call.
The following table describes how Oracle9iAS Portal handles the cookies generated
by the providers as well as the cookies sent to the providers during the initSession
and Show calls based on various provider attributes.
| Type of provider | Same cookie domain | Cookies received by providers during initSession/do_login | Cookies received by providers during portlet Show |
Provider cookies set up at the Web Browser by portal |
Provider cookies are stored in portal's session store |
| Database | N/A | All cookies that are set up at the browser * | All cookies that are set up at the browser * | Yes | No |
| Web | Yes | All cookies that are set up at the browser * | All cookies that are set up at the browser * | Yes | No |
| Web | No | Cookies owned by that provider. These are retrieved from session store. | Cookies owned by that provider. These are retrieved from session store. |
No |
Yes |
* This list includes the provider cookies from all providers that are in the same cookie domain as the portal.
Synchronization of Provider Session and Portal Session
This section applies to the Web providers. The portal session and the provider sessions are synchronized to avoid problems when the provider session times out or becomes invalid while the portal session remains valid. This is not an issue for providers that are configured with a login frequency of 'ALWAYS' but for providers that have the login frequency set to 'Once per user session' it is a critical consideration. Since the initSession() call is not made prior to every page request, any session inconsistency will be detected only during the provider's render/show request.
To avoid the problem of provider and portal sessions going out of sync, the portal allows the providers to return a time out value indicating the interval until the session expires. The portal uses this value to determine if the initSession() call is to be made in the session. The call to initSession() in this case is made at an offset before the interval specified by the provider along with the existing provider cookies. This allows the providers to validate the session cookie and regenerate the cookie if the session has changed.
Note: The portal handles only the case that's interval based where the provider session becomes invalid after certain period of time. Invalid Provider sessions due to other reasons like a reboot etc. are not handled in the current version.
Session Sharing
When applications are integrated into Oracle9iAS Portal by creating a provider, the application and provider maintain distinct sessions. Logging into the application creates a user session and when the same user accesses the portal to view the portlet, the provider establishes another session with the application. Session sharing allows providers to share the same session as that of the applications. For more details on session sharing refer to the document 'Integrating Password-Protected applications with Oracle9iAS Portal'. This document can be found on Oracle Technology Network.
Provider Integration FAQ
The cookies should be sent to the portal during the initSession call for Web providers and do_login call for database providers. These cookies will be made available during the show request to the providers from the Parallel Page Engine.
If the providers are configured to be on the same cookie domain as the portal, the cookies that are forwarded by the portal to the Client browser will be accepted by the browser and get stored.
The Provider should create the cookies in the do_login/initSession call and send it to the portal. The portal will send the cookies received from the provider along with the page layout information to the Parallel Page Engine in the middle tier. These cookies will be used by the Parallel Page Engine when it makes show/render requests to the providers. Middle-Tier which includes the Parallel Page Engine does not store any cookies as such.
Same as answer to Question 3.
Same as answer to Question 3 but in addition the Provider should specify the proxy settings in the Global Settings page and indicate during registration that Proxy is required for the communication between Portal and Provider.
Same as answer to Question 3 but indicate during registration that it is on a different cookie domain by not checking the same cookie domain check box.
When a user requests a page, all the providers that are are contributing content (portlets) in the page are contacted for do_login/initSession based on the login frequency. If the initSession is already called for a provider in the current user's session (assuming the setting in provider registry is "Once per user Session") then portal does not call the initSession for subsequent requests and applies the cookies from the previous initSession()/do_login() call to the show requests. InitSession() calls originate from the database and they are sequential for the providers (in random order) participating in the page.
Same as above with the only difference being that the call to InitSession() is made every time a page request containing the portlets from that provider comes in.
The initSession/do_login call originates from the database and the calls are made sequentially.
Revision History: