Oracle9iAS Portal Developer Kit
Understanding the Default Provider

In the portal architecture, the portal never talks to a portlet directly. It uses an interface we call 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 drive portlet operations. 

The PDK-Java (JPDK) include a set of interfaces called Web Provider Interfaces.  The Web Provider Interfaces specify the functions required by your Java implementation to properly operate as part of the Portal.  The set of Web Provider Interfaces include:

The Provider Interfaces specify what kind of implementation is required without actually providing that implementation.  Providing the implementation for each of the Provider Interfaces is handled by the Provider Runtime.  The Provider Runtime is a set of classes that implement the Provider Interfaces in the servlet environment.  These are the classes you will use and build upon to create your portlets and expose them to the Oracle9iAS Portal.  The Provider Runtime corresponding to the Provider Interfaces are:

The Provider interface, one of a set of Web Provider Interfaces, specifies the functions required by a provider to work as part of the Portal.  The ProviderRuntime offers you a base implementation of this interface called oracle.portal.provider.v1.http.DefaultProvider.  The DefaultProvider is a class file and performs all of the functions required by the Provider interface.  

This article introduces you to the functions and capabilities of the DefaultProvider.   The article is broken into two sections.  First, it discusses how the DefaultProvider uses a declarative mechanism to determine and instantiate the portlets it manages.  This declaration is provided through an .xml file rather than programmatically.  Second, the article describes the behavior the DefaultProvider implements for each method defined by the Provider interface.

Understanding the behavior of the methods will give you the knowledge needed to determine when and how to override and extend the behavior of the methods within the DefaultProvider. 

CONFIGURATION

The main function of a Provider is to manage a set of Portlets.  The DefaultProvider uses the declarative mechanism to allow you to specify and register your Portlets in a static file.  It allows the DefaultProvider to list and activate a set of portlets.  The declarative mechanism used by the DefaultProvider is an .xml file called provider.xml.  The provider.xml file has the following characteristics:

The DefaultProvider locates the provider.xml by using the "provider_root" argument from the Oracle HTTP Server (9i Application Server).  Once located, the DefaultProvider parses this file and creates an instance for each portlet specified in the file.  For this article, an instance refers to a java object.  It associates each of the portlet tags with each newly created portlet instance.  The DefaultProvider then creates an instance for each render mode specified and associates it with the value of its portlet tag. Finally, the DefaultProvider creates a list of portlets and adds each newly instantiated portlet to the list.

 The DefaultProvider parses the provider.xml when the provider instance is created.  The provider instance is created only once during the initial call from Oracle9iAS Portal.  Therefore, any changes or modifications made to the provider.xml after the provider has been instantiated will require the Web listener be restarted.  This forces the DefaultProvider to re-create the provider instance and re-parse the provider.xml file.

As stated previously, the DefaultProvider uses a declarative mechanism stored in the file system.  If you would rather store this declaration in a database server, you can subclass the DefaultProvider and override the getProviderRegistry(ServletConfig sc) method.

In-depth information on the structure and contents of the provider.xml can be found by reviewing the  Provider XML Tag Reference .

BEHAVIOR

The DefaultProvider is the first line of communication from Oracle9iAS Portal (through the Provider Adapter) when retrieving portlet information and rendering a portlet.  Because it carries out the functions of a provider, it must return a list of information to the Portal when requested.  

Once it receives the initial call from Oracle9iAS Portal, the DefaultProvider uses it methods to complete a set of determined functions.  The methods within within the DefaultProvider work together to answer all of the requests from the Portal. 

This sections describes the function of each method within the DefaultProvider.  By understanding when the method is called and the function of each method, you can determine when subclassing and overriding is necessary.

init(long providerId, ProviderLog logger)

The init method is called by the Provider Adapter to initialize the provider.  One instance is created per provider ID.  Do not override this method. 

getProviderId( )

The getProviderId method is called when the provider is initialized and returns the provider ID associated with this provider instance.  Do not override this method.

getVersion( )

The getVersion method is called when the provider is initialized and returns the Oracle9iAS Portal Developer Kit version.  The version returned by this method is 1.  Do not override this method.

getSubscriber()

The getSubscriber() method is called when the Provider is registered if a Provider key has been entered during Provider registration with Oracle9i AS Portal.  The method returns null by default.

Subclass and override this method if you want to use a subscription-based model.  In a subscription-based model, a company associate its own ID with a Portal.  This is sometimes done for billing purposes.

register(String subscriberId, String portalVersion)

The register method is called when the provider is initialized and it initializes a personalization manager (if available) for each portlet. The register method may also use a subscriberId for subscription billing.

An encryption key allows the provider to trust the Portal and eliminates the middle man (SSL).  If an encryption key is entered, the register method will pass the following back to the Portal.

Subclass and override this method when using a subscriberID for subscription billing and to enable encryption.

deregister( )

The deregister method is called when a provider has been removed.  It destroys the personalization manager for each portlet.  Do not override this method.

initSession(ProviderUser user ExternalPrincipal externalApp)

The initSession method is called based on the setting in the provider registration page of Oracle Portal.  The method creates an Http Session. s of Portal 3.0.8 use initSession that receives the externalApp parameter specifically for External Application portlets.

Subclass and override this method when creating additional sessions.  All cookies that will be passed throughout the session must be created within this method.

setSession(java.lang.String session)

Controls whether this provider starts a (servlet) session in its initSession(ProviderUser,ExternalPrincipal) method.

getProviderRepositoryPath()

The getProviderRepositoryPath is called when instantiating the provider, it gets the path location of the Provider Definition file.

getPortlets(int start, int count, boolean byUser, ProviderUser user)

The getPortlets method is called when a view the portlet list from Oracle9iAS Portal or refreshes the portlet repository.  The method creates a list portlets with the ability to limit by user. 

Subclass and override this method to limit the portlet list by user.

getPortlet(long id, ProviderUser user)

The getPortlet method is called when displaying a portlet.  The method returns information for a specified portlet. 

Subclass and override this method to change the way the portlet is called.

addPortlet(java.lang.Object portlet)

The addPortlet method is called during the parsing of the provider.xml file to associate a portlet as a child of this provider.

getProviderContext()

The getProviderContext method is called during portlet rendering to get the parameters whose values are Objects mapped to String names.

getUseOldStyleHeaders()

This method is called when parsing the provider.xml file.  It signals to the provider whether the PortletRendererUtil will render headers and footers for this provider's portlets in the style used by a 3.0.6 version of Oracle9iAS Portal or earlier.

setUseOldStyleHeaders(boolean useOldStyleHeaders)

The setUseOldStyleHeaders methods specifies whether or not PortletRendererUtil should render headers and footers for this provider's portlet in the style used by a 3.0.6 version of Oracle9iAS Portal or earlier.

isReloadRequired(int action)

The isReloadRequired method is called when portal sends a getPortlet() or getPortlet() request to the provider.  If the auto_reload=true parameter has been set in the Provider Definition file, it checks to see if the Provider Definition file has been updated since the last request from portal.

log(String msg)

The log method is called when any methods are called.  It writes log information to the servlet log. 

Subclass and override this method to change the location of the log file.

For more information on each of the above methods, please review the PDK-Java documentation.

Revision History: