oracle.portal.provider.v1
Interface Provider

All Known Subinterfaces:

ProviderXtra, ProviderXtra2

public interface Provider

A Provider manages a set of portlets. As such it is the conduit between the Portal Adapter and a given portlet. I.e. calls are mapped to portlets their controllers by calling Provider APIs. Thus the primary function of the Provider interface is to expose its portlets to a Portal. As a manager it additionally takes on the role of "application" manager. That is the Provider is used to expose function that is shared between the portlets it is managing. In the JPDK shared function is (commonly) controlled via a session. The session is created and maintained by the Provider.

Method Summary

void	deregister() Deregister this provider.
Portlet	getPortlet(long id, ProviderUser user) Returns a Portlet by its Id.
Portlet[]	getPortlets(int start, int count, boolean byUser, ProviderUser user) Returns array of Portlets managed by this Provider.
long	getProviderId() Returns this provider's ID.
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.
int	getVersion() Provider's version -- version of the PDK API it implements.
void	init(long providerId, ProviderLog logger) Initialize the provider.
java.lang.Object[]	initSession(ProviderUser user) 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.
java.lang.Object[]	initSession(ProviderUser user, ExternalPrincipal externalApp) Called to initialize the Provider in a particular user session.
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.

Method Detail

init

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

Initialize the provider. Basically all this does is set the providerId. This can't be set at create time because of the need to use a null constructor.

Parameters:

providerId - this providers ID.

logger - logging mechanism this provider should use. If null the provider may implement a default logging facility (but is not required to do so).

getProviderId

public long getProviderId()

Returns this provider's ID.

getProviderRepositoryPath

public java.lang.String getProviderRepositoryPath()

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

Returns:

a physical storage path, or null if not applicable

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

Returns:

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

getVersion

public int getVersion()

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

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. The Provider should do its per portal initialization here.

In some cases, such as when customers are billed on a subscription basis for using a particular provider, a Provider needs to distinguish the particular portal being registered. This is supported by passing a subscriberId to the register method. A subscriberID is controlled by the Provider owner. A portal customer requests/receives a subscriber ID from the Provider owner when they "purchase" the service. This subscriberId is entered by the portal customer when the Provider is installed/registered. The portal in turn sends this ID to the Provider software to complete the registration. Providers that don't support this subscription model will receive a null subscriberID.

This mechanism is also used to enhance security. Along with the subscriberId a Provider can supply an encryption key to the portal customer. If provided, the portal encrypts all requests to the Provider using this key. The request then sent to the Provider with the subscriberID encoded in the requests header. The Provider uses the subscriberID to identify the proper key to use for decryption.

Recognizing that certain Providers would like the enhanced security that encrpyted messaging supports but don't want to deal with providing a non-programmatic mechanism for communicating the encryption key to the portal customer, the register() method can alternatively generate a subscriberID and encryption key that it returns to the registering portal for use with all subsequent requests. Currently, this id/key pair must be communicated over an unsecure channel making this a less then bullet-proof mechanism. However, given that all subsequent messages occur in a secure manner, the level of security to the Provider is greatly enhanced.

Providers that don't dynamically generate and return an id/key pair should return null.

Parameters:

subscriberId - Subscriber identifier the portal customer supplied when registering the Provider in the Portal UI. If none was provided this value is null.

PortalVersion - the version of the portal registering this provider. In the typical Oracle form: 1.0.1.0.1.

Returns:

If this Provider dynamically generates an encryption key to be used to secure subsequent requests from this portal then a ProviderSubscriber, null otherwise.

deregister

public void deregister()
                throws ProviderException

Deregister this provider. Indicates this Provider is no longer in use in the specified portal. The specific portal is inferred from the providerId which Oracle Portal attempts to make unique across all portals. Providers typically respond to this call by unsubscribing the customer and or deleting the entries in the portlet (personalization) repository that correspond to this provider/portal.

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 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.

externalApp - External Applciation 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 array is constrained to the specified range. If byUser is true, then the array is further constrained to only those Portlets that the passed user has priveleges to.

Parameters:

start - The starting element in the range being requested. This value is 0 based. I.e. a start of 0 indicates the first element in the set.

count - The number of elements in the range. The returned array should contain a maximum of count elements.

byUser - If true then the set should be restricted to those portlets this user has access privileges to.

user - The user on whose behalf this request is being made. Used to both validated that this user has the privileges to make this request, to get access to session state if needed, and to restrict the response set if byUser is true.

Returns:

An array of Portlets constrained to the passed criteria. The array's length must equal the number of returned elements. I.e. the caller can count on array.length to describe the number of valid entries. If no portlets match the constaints then the call can return either null or a zero length array.

getPortlet

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

Returns a Portlet by its Id. Only return if user has access otherwise null is returned.

Parameters:

id - Portlet Id.

user - The user on whose behalf this request is being made. Used to both validated that this user has the privileges to make this request, to get access to session state if needed, and most importantly to check if this user has access privileges to this portlet.

Returns:

the Portlet that maps from this id, null otherwise. If non-null, it signifies that this user has access privileges to this 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.

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