oracle.portal.provider.v1.http
Class DefaultProvider

java.lang.Object
  |
  +--oracle.portal.provider.v1.http.DefaultProvider

public class DefaultProvider

extends java.lang.Object

implements ProviderXtra2, Initializable

The DefaultProvider is the JPDKs base implementation class for the Provider interface. It not only implements default/common behaviors for the Provider's method, but as importantly, is responsible for bootstrapping all the portlets and their components. This later function is managed by processing the provider.xml file which describes the characteristics of each portlet managed by this provider.

When the DefaultProvider is instantiated by the HttpProvider servlet, the instance processes the provider.xml file. For each portlet (and controller) described in the file, the DefaultProvider creates the instance and pushes the corresponding meta and configuration data.

Constructor Summary

DefaultProvider()

Method Summary

void	addPortlet(java.lang.Object portlet) Called during the processing of provider.xml to associate a portlet as a child of this provider.
void	deregister() Deregister this provider.
PortletContainerRenderer	getContainerRenderer() Returns the default portlet container renderer The portlet container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports.
int	getDebugLevel() Returns the current debug level.
Portlet	getPortlet(long id, ProviderUser user) Returns the Portlet with the given ID.
Portlet[]	getPortlets(int start, int count, boolean byUser, ProviderUser user) Returns array of Portlets managed by this Provider.
ParameterMap	getProviderContext() Gets the ParameterMap which contains the Provider's contextual information.
long	getProviderId() Returns this provider's ID.
ProviderLog	getProviderLog() Returns the ProviderLog associated with this Provider.
java.lang.String	getProviderRepositoryPath() Gets the default storage path used for meta data associated with this provider, if any
ProviderSubscriber	getSubscriber() Returns the subscriber for this portal.
boolean	getUseOldStyleHeaders() Deprecated. use get/setContainerRenderer() to specify the default container renderer that should be used to render portlet containers for this provider
int	getVersion() Provider's version -- version of the PDK API it implements
void	init(long providerId, ProviderLog logger) Initialize the provider.
void	init(ParameterMap param) Performs the steps necessary to fully initialize this DefaultProvider.
java.lang.Object[]	initSession(ProviderUser user) Deprecated. As of Portal 3.0.8 use initSession that receives the externalApp parameter.
java.lang.Object[]	initSession(ProviderUser user, ExternalPrincipal externalApp) Called to initialize the Provider in a particular user session.
boolean	isDebugEnabled() Returns true if debug mode is enabled.
boolean	isReloadRequired(int action) Used to determine if this provider needs to be re-initialized from the provider.xml file.
void	log(java.lang.String msg) Writes the specified message to a provider log, which is usually an event log.
void	log(java.lang.String message, java.lang.Throwable throwable) Writes the stack trace and an explanatory message for a given Throwable exception to the provider log file.
ProviderSubscriber	register(java.lang.String subscriberId, java.lang.String portalVersion) Register this newly created provider.
void	setContainerRenderer(java.lang.Object renderer) Sets the default portlet container renderer The container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports Each portlet can specify it's own container renderer and you can specify a default at the provider level to be used by any portlet that does not explicitly specify it's own container renderer
void	setContainerRenderer(PortletContainerRenderer renderer) Sets the default portlet container renderer The container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports Each portlet can specify it's own container renderer and you can specify a default at the provider level to be used by any portlet that does not explicitly specify it's own container renderer
void	setSession(java.lang.String session) Controls whether this provider starts a (servlet) session in its initSession(ProviderUser,ExternalPrincipal) method.
void	setUseOldStyleHeaders(boolean useOldStyleHeaders) Deprecated. use setContainerRenderer(new ContainerRenderer306()) to get equivalent behavior. Alternatively, create your own container renderer by extending PortletContainerRenderer
void	setUseOldStyleHeaders(java.lang.String useOldStyleHeaders) Deprecated. use setContainerRenderer(new ContainerRenderer306()) to get equivalent behavior. Alternatively, create your own container renderer by extending PortletContainerRenderer

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultProvider

public DefaultProvider()

Method Detail

init

public void init(long providerId,
                 ProviderLog logger)
          throws ProviderException

Initialize the provider. Simpliest use is to just set the data members (ProviderID and logger) that correspond to this new instantiated provider. It is also valid to register the provider if new or "acquire" the provider if it already exists. Though in the former case the register() method should ultimately be called and the work done there. The DefaultProvider processes the provider.xml file here, bootstrapping the portlets it manages.

Parameters:

providerId - the portal provider identifier this instance represents.

logger - the system the Provider uses to log error and status messages to.

init

public void init(ParameterMap param)
          throws ProviderException

Performs the steps necessary to fully initialize this DefaultProvider.

Specified by:

init in interface Initializable

Parameters:

parameters - a ParameterMap containing all parameters necessary to initialize the object.

Throws:

ProviderException - if an error occurs whilst trying to initialize.

getProviderContext

public ParameterMap getProviderContext()

Gets the ParameterMap which contains the Provider's contextual information.

setUseOldStyleHeaders

public void setUseOldStyleHeaders(boolean useOldStyleHeaders)

Deprecated. use setContainerRenderer(new ContainerRenderer306()) to get equivalent behavior. Alternatively, create your own container renderer by extending PortletContainerRenderer

Specifies whether or not PortletRendererUtil should render headers and footers for this provider's portlets in the style used by a 3.0.6 portal or earlier, rather than the style used by a post-3.0.6 portal.

Parameters:

useOldStyleHeaders - boolean indicating which style of form headers and footers should be rendered by PortletRendererUtil.true - render portal 3.0.6 style headers and footers. false - render new style headers and footers.

setUseOldStyleHeaders

public void setUseOldStyleHeaders(java.lang.String useOldStyleHeaders)

Deprecated. use setContainerRenderer(new ContainerRenderer306()) to get equivalent behavior. Alternatively, create your own container renderer by extending PortletContainerRenderer

Specifies whether or not PortletRendererUtil should render headers and footers for this provider's portlets in the style used by a 3.0.6 portal or earlier, rather than the style used by a post-3.0.6 portal.

Parameters:

useOldStyleHeaders - String representation of boolean ("true" or "false") indicating which style of form headers and footers should be rendered by PortletRendererUtil.

See Also:

setUseOldStyleHeaders(boolean)

getUseOldStyleHeaders

public boolean getUseOldStyleHeaders()

Deprecated. use get/setContainerRenderer() to specify the default container renderer that should be used to render portlet containers for this provider

Signals whether PortletRendererUtil will render headers and footers for this provider's portlets in the style used by a 3.0.6 portal or earlier, rather than the style used by a post-3.0.6 portal.

Returns:

boolean indicating which style of form headers and footers should be rendered by PortletRendererUtil.true - render portal 3.0.6 style headers and footers. false - render new style headers and footers.

addPortlet

public void addPortlet(java.lang.Object portlet)
                throws ProviderException

Called during the processing of provider.xml to associate a portlet as a child of this provider.

Parameters:

portlet - portlet to be added to this provider. Should implement the Portlet interface.

Throws:

ProviderException - if the given object is not a valid Portlet

setSession

public void setSession(java.lang.String session)

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

Parameters:

session - String representation of boolean value. Should be "true" if this provider is to start a session in initSession, or "false" otherwise.

getProviderRepositoryPath

public java.lang.String getProviderRepositoryPath()

Gets the default storage path used for meta data associated with this provider, if any

Returns:

the filesystem path to the directory containing provider.xml

getProviderId

public long getProviderId()

Returns this provider's ID.

getVersion

public int getVersion()

Provider's version -- version of the PDK API it implements

getSubscriber

public ProviderSubscriber getSubscriber()

Returns the subscriber for this portal. In a subscription-based model a company may want/need to associate its own ID with a customer/portal. This ID could be used for billing purposes, for example. When a Provider is registered in a Portal, the subscriber ID is entered by the administrator and passed to the Provider in the register method. Once established, the Provider is expected to maintain the relationship between the ProviderId and the subscriberID (persistently). The Default Provider doesn't support maintaining a persistant association between the subscriptionID and providerId, hence it always returns null. Subclass and override if you need this behavior.

Returns:

the subscriber. null if this Provider doesn't use/support subscription.

register

public ProviderSubscriber register(java.lang.String subscriberId,
                                   java.lang.String portalVersion)
                            throws ProviderException

Register this newly created provider. Having your register method called means your Provider has just been installed/activated in a portal. It is assumed the (new) providerID has already been made available via init();

In response to this method call, the DefaultProvider enumerates its Portlets and for each Portlet that has a PersonalizationManager, it invokes the PersonalizationManager init(Portlet p) method. This gives the Portlet's PersonalizationManagers the opportunity to do one time initialization.

Recognizing that many providers want a lightweight mechanism for securing the communication between them and the portal, register has an additional optional function. In addition to SSL/HTTPS support, the portal supports a simple key encryption mechanism. In this case, the administrator is expected to receive the encryption key (along with a subscriber id) from the organization providing the service. The subscriber ID and the encryption key are entered when the administrator registers the provider in the portal. All communication between the portal and the provider are encrypted using this key.

The major drawback of this facility is the service provider must provide a mechanism for supplying the key in the first place. When a service provider merely wants a more secure communication link between the portal and itself but doesn't require complete/guaranteed security, we allow the the provider to return the subscriber ID and encryption key from the register method. Though, obviously, this communication occurs in open text and can therefore be compromised, it ensures that all subsequent communication is encrypted, greatly reducing the opportunity for misbehavior.

The DefaultProvider doesn't support using encryption keys. Hence it always returns null. Subclass and override to add this behavior.

Parameters:

subscriberId - Provider defined key customer supplies when the provider is registered in the portal. It is expected the Provider will use this key information to help provision this instance.

portalVersion - the version number of the portal you are being registered with.

Returns:

the dynamically generated subscriber containing both the subscriberId and the encryption key. This value should only be non-null if the key/subscriber is dynamically generated. null should be returned if the encryption key is entered by the administrator when registering the Provider or encryption isn't used. Currently, the DefaultProvider doesn't implement encryption support, hence always returns null.

deregister

public void deregister()
                throws ProviderException

Deregister this provider. A Provider's deregister method is called when the Provider is removed from a portal. In response to this, the DefaultProvider calls destroy(Portlet p) on each PersonalizationManager used by its Portlets. Calling destroy() allows each Personalization manager to remove or cleanup its repository. For example it can delete all entries associated with this provider (Id).

initSession

public java.lang.Object[] initSession(ProviderUser user,
                                      ExternalPrincipal externalApp)
                               throws ProviderException

Called to initialize the Provider in a particular user session. This may be called never, once per user session, or once per request depending on how the provider is configured in the portal. If the Provider uses HTTP cookies or maintains state via a cookie-based HTTP session, it is imperative that (all) cookies be established during this call.

A session is established via the ProviderUser user object. I.e. the user object contains the methods for creating and retrieving a session. For HttpProviders, further HTTP-specific information can be accessed by casting the user object to a ServletProviderUser. In particular, this allows access to any existing Cookies already established between the user and provider, via the ServletProviderUser.getCookies() method.

As this interface is designed for use in both servlet and non-serlvet environments servlet interfaces could not be used. initSession returns an array of cookie objects of the type expected in the particular framework the provider is executing in. For HttpProviders this is servlets and hence the returned object array should contain objects of type javax.servlet.http.Cookie.

Note: in order to support backwards compatibility for providers that subclass the DefaultProvider and override initSession(), the current implementation of this method merely turns around and calls the old deprecated form of initSession(). This ensures that subclasses with existing overrides continue to work unchanged. If you have implemented such a subclass consider this when you "upgrade" to the new form of initSession(). I.e. if your initSession() (new form) calls super() remember this will in turn call the old form of initSession(). If you haven't removed your old form or modified its implementation your code could redo/overwrite work you have already done in the new form of initSession. Our recommendation is to remove your existing (old form) initSession() when upgrading to the new form. This means all will continue to work correctly when we remove the deprecated old form in the future.

Parameters:

user - Current portal user.

externalApp - External Application information (if it exists).

Returns:

Array of cookie objects. null if this provider doesn't use cookies or relies on the (user) session to maintain its state. The type of these objects is specific to the environment in which this provider runs. When running in the servlet environment (HttpProviders) these objects should be of type javax.servlet.http.Cookie.

Throws:

ProviderException - ProviderException is a generic exception for Providers.

AuthenticationException - AuthenticationException should be thrown if you have an external application that requires additional authentication and that authentication fails for some reason.

initSession

public java.lang.Object[] initSession(ProviderUser user)
                               throws ProviderException

Deprecated. As of Portal 3.0.8 use initSession that receives the externalApp parameter.

Called to initialize the Provider in a particular user session. This may be called never, once per user session, or once per request depending on how the provider is configured in the portal. If the Provider uses HTTP cookies or maintains state via a cookie-based HTTP session, it is imperative that (all) cookies be established during this call.

A session is established via the user object. I.e. the user object contains the methods for creating and retrieving a session.

As this interface is designed for use in both servlet and non-serlvet environments servlet interfaces could not be used. initSession returns an array of cookie objects of the type expected in the particular framework the provider is executing in. For HttpProviders this is servlets and hence the returned object array should contain object of type javax.servlet.http.Cookie.

Parameters:

user - Current portal user.

Returns:

Array of cookie objects. null if this provider doesn't use cookies or relies on the (user) session to maintain its state. The type of these objects is specific to the environment in which this provider runs. When running in the servlet environment (HttpProviders) these objects should be of type javax.servlet.http.Cookie.

Throws:

ProviderException - ProviderException is a generic exception for Providers

getPortlets

public Portlet[] getPortlets(int start,
                             int count,
                             boolean byUser,
                             ProviderUser user)
                      throws ProviderException

Returns array of Portlets managed by this Provider. The range of Portlets being requested are controlled by start and count. Providers should return only count Portlets starting at start. If there are fewer then count Portlets then a shorter array is returned.

The Portlets returned by getPortlets() are constrained to those the user is authorized to access if byUser is true.

The DefaultProvider implements these semantics based on the set of portlets registered with it via the provider.xml descriptor file.

Parameters:

start - The ordinal of the first portlet that should be returned.

count - The maximum number of portlets that should be returned.

byUser - If true, indicates the returned list is constrained to those portlets the user is authorized to access.

user - The current user on whose behalf the request is being made.

Returns:

array of portlets constrained to the indicated range.

getPortlet

public Portlet getPortlet(long id,
                          ProviderUser user)
                   throws ProviderException

Returns the Portlet with the given ID. The Portlet should only be returned if the user is authorized to access it.

The DefaultProvider implements this semantic based on the set of portlets registered with it via the provider.xml descriptor file.

Parameters:

id - Portlet Id.

user - Current user.

Returns:

the Portlet associated with the given Id. null if no portlet matches that Id or if the user isn't authorized to access the portlet.

log

public void log(java.lang.String msg)

Writes the specified message to a provider log, which is usually an event log. The message provides explanatory information about an exception or error or an action the provider takes. The name and type of the provider log file is specific to the provider engine. For Provider's running in the servlet environment, the log is the servlet log.

Parameters:

msg - a String specifying the explanatory message to be written to the log file

log

public void log(java.lang.String message,
                java.lang.Throwable throwable)

Writes the stack trace and an explanatory message for a given Throwable exception to the provider log file. The stack trace is part of the Throwable object, and the message is the one you specify in the message parameter. The name and type of the provider log file is specific to the provider engine, but it is usually an event log.

Parameters:

message - a String that describes the error or exception

throwable - the Throwable error or exception

getContainerRenderer

public PortletContainerRenderer getContainerRenderer()

Returns the default portlet container renderer The portlet container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports. Each portlet can specify it's own container renderer and you can specify a default at the provider level to be used by any portlet that does not explicitly specify it's own container renderer

Returns:

the portlet container renderer or null if the provider does not have a default container renderer

setContainerRenderer

public void setContainerRenderer(PortletContainerRenderer renderer)
                          throws ProviderException

Sets the default portlet container renderer The container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports Each portlet can specify it's own container renderer and you can specify a default at the provider level to be used by any portlet that does not explicitly specify it's own container renderer

Parameters:

renderer - the portlet container renderer

setContainerRenderer

public void setContainerRenderer(java.lang.Object renderer)
                          throws ProviderException

Sets the default portlet container renderer The container renderer is responsible for rendering the portlet container in each of the show modes the portlet supports Each portlet can specify it's own container renderer and you can specify a default at the provider level to be used by any portlet that does not explicitly specify it's own container renderer

Parameters:

renderer - the default portlet container renderer. Even though the type of the parameter is Object, the parameter must be an instance of PortletContainerRenderer

isReloadRequired

public boolean isReloadRequired(int action)

Used to determine if this provider needs to be re-initialized from the provider.xml file.

The mechanism used should work when providers are load-balanced. This means it cannot be drived by communication from the portal such as a repository refresh (as it used to be) because only one server will receive the refresh request and reloaded the definition. This leads to the servers being out of sync.

The simplest way to do this is to trigger reload (or at least a modification check) on a time interval.

This feature requires auto-reload to be enabled.

Specified by:

isReloadRequired in interface ProviderXtra2

Parameters:

action - not currently used

isDebugEnabled

public boolean isDebugEnabled()

Returns true if debug mode is enabled. Debug mode enabled is determined by the Debug Level being greater than zero

Specified by:

isDebugEnabled in interface ProviderXtra2

getDebugLevel

public int getDebugLevel()

Returns the current debug level.

Specified by:

getDebugLevel in interface ProviderXtra2

getProviderLog

public ProviderLog getProviderLog()

Returns the ProviderLog associated with this Provider.

Specified by:

getProviderLog in interface ProviderXtra2

Tags copied from interface: ProviderXtra2

Returns:

the ProviderLog associated with this provider