oracle.portal.provider.v2
Class ProviderInstance

java.lang.Object
  oracle.portal.provider.v2.ProviderInstance

public class ProviderInstance
extends java.lang.Object

A ProviderInstance is the entity that carries out the responsibilities of a single 'instance' of a provider registered on a single Portal. Generally, a ProviderInstance is driven by meta data information in a ProviderDefinition that may be shared with other ProviderInstances registered on different portals.

Field Summary

static java.lang.String

PROVIDER_USER The constant that is used as the key for retrieving the ProviderUser from the ProviderSession.

Constructor Summary

ProviderInstance()

Method Summary

void	deregister() Deregister this provider instance.
byte[]	exportData(boolean exportUsers, java.lang.String[] userNames, TransportLogger logger) Exports provider level data from this ProviderInstance.
CipherManager	getCipherManager() Gets the the CipherManager which will be employed to encrypt exported data.
java.lang.String	getContextPath() Returns a string which uniquely indentifies this ProviderInstance .
OidManager	getOidManager() Gets the OID Manager that provides access to the OID repository.
PortletDefinition	getPortletDefinition(long portletId, ProviderUser user) Returns the PortletDefinition with the given ID.
PortletDefinition	getPortletDefinition(long portletId, ProviderUser user, boolean securityCheck) Returns the PortletDefinition with the given ID.
PortletDefinition[]	getPortletDefinitions(boolean byUser, ProviderUser user) Returns an array of PortletDefinition objects for all of the portlets managed by this Provider.
PortletDefinition[]	getPortletDefinitions(int start, int count, boolean byUser, ProviderUser user) Returns array of PortletDefinition objects for the portlets managed by this Provider.
PortletInstance	getPortletInstance(long portletId, java.lang.String portletInstanceName, ProviderUser user) Deprecated. Use getPortletInstance(long, String, ProviderUser, PerfMonitor) instead.
PortletInstance	getPortletInstance(long portletId, java.lang.String portletInstanceName, ProviderUser user, java.util.Locale defaultLocale) Deprecated. Use getPortletInstance(long, String, ProviderUser, Locale, PerfMonitor) instead.
PortletInstance	getPortletInstance(long portletId, java.lang.String portletInstanceName, ProviderUser user, java.util.Locale defaultLocale, PerfMonitor monitor) Constructs a PortletInstance object based on the specified information.
PortletInstance	getPortletInstance(long portletId, java.lang.String portletInstanceName, ProviderUser user, java.util.Locale defaultLocale, PerfMonitor monitor, boolean securityCheck) Constructs a PortletInstance object based on the specified information.
PortletInstance	getPortletInstance(long portletId, java.lang.String portletInstanceName, ProviderUser user, PerfMonitor monitor) Constructs a PortletInstance object based on the specified information.
PreferenceStore	getPreferenceStore() Gets the default PreferenceStore that should be used by the ProviderInstance and all its child objects for which a preference store has not been chosen explicitly.
ProviderContext	getProviderContext() Gets the context object that describes the deployment environment of the provider.
java.lang.String	getProviderId() Returns the provider's ID.
ProviderSubscription	getSubscription() Returns the subscription information for this portal.
boolean	getUseOldStyleHeaders() Deprecated. use ProviderDefinition.getContainerRenderer() to determine the default container renderer that should be used to render portlet containers for this provider
void	importData(byte[] data, TransportLogger logger) Imports provider level data into this ProviderInstance, for example by updating an associated persistant store.
void	init(java.lang.String providerId, ProviderDefinition definition) Initializes the provider instance after construction.
java.lang.Object[]	initSession(ProviderUser user, ExternalPrincipal externalApp) Called to initiate a session with a particular user.
boolean	isDefinitionEqual(ProviderDefinition pd) Compare the internal ProviderDefinition with that specified.
ProviderRegistrationInfo	register(java.lang.String subscriptionId, java.lang.String portalVersion) Register this newly created provider instance.

Methods inherited from class java.lang.Object

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

Field Detail

PROVIDER_USER

public static final java.lang.String PROVIDER_USER

The constant that is used as the key for retrieving the ProviderUser from the ProviderSession. This is provided as an alternative way to reference the current user.

See Also:

Constant Field Values

Constructor Detail

ProviderInstance

public ProviderInstance()

Method Detail

init

public void init(java.lang.String providerId,
                 ProviderDefinition definition)
          throws ProviderException

Initializes the provider instance after construction.

Parameters:

providerId - the provider's ID, assigned by Portal.

definition - provider definition object holding meta data for this provider.

Throws:

ProviderException

getProviderId

public java.lang.String getProviderId()

Returns the provider's ID.

getProviderContext

public ProviderContext getProviderContext()

Gets the context object that describes the deployment environment of the provider. Generally, all providers running in the same environment share the same ProviderContext.

Returns:

context object describing the deployment environment of the provider.

getUseOldStyleHeaders

public boolean getUseOldStyleHeaders()

Deprecated. use ProviderDefinition.getContainerRenderer() to determine 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.

getSubscription

public ProviderSubscription getSubscription()

Returns the subscription information for this portal. In a subscription-based model a company may want/need to associate its own ID or key with a customer/portal. This key can then be used to identify the each subscriber as requests are received. This information can be used to bill subscribers for using the provider.

For example, when a ProviderInstance is registered in a Portal, the subscription key is entered by the portal administrator and passed to the ProviderInstance in the register method.

Any persistent mapping that is required between the subscription key and any other provider specific information (eg an account number) must be established and maintained by extending ProviderInstance.

Returns:

the subscription, or null if this ProviderInstance doesn't use / support subscription.

register

public ProviderRegistrationInfo register(java.lang.String subscriptionId,
                                         java.lang.String portalVersion)
                                  throws ProviderException,
                                         java.io.IOException,
                                         AccessControlException

Register this newly created provider instance. Having your register method called means your Provider has just been registered in a portal. This instance's provider ID will already have been set via a call to init(java.lang.String, oracle.portal.provider.v2.ProviderDefinition).

In response to this method call, the ProviderInstance enumerates its PortletDefinitions and calls PortletDefinition.register(oracle.portal.provider.v2.ProviderInstance) on each of them. This gives the PortletDefinition the opportunity to do some one time initialization for this ProviderInstance.

Parameters:

subscriptionId - 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:

an object containing the dynamically generated subscription information and/or encryption key. The properties on this object will override the defaults specified by the portal administrator.

Throws:

ProviderException

java.io.IOException

AccessControlException

deregister

public void deregister()
                throws ProviderException

Deregister this provider instance. This method is called when the provider is deregistered or removed from a portal.

In response to this method call, the ProviderInstance enumerates its PortletDefinitions and calls PortletDefinition.deregister(oracle.portal.provider.v2.ProviderInstance) on each of them. This gives the PortletDefinition the opportunity to destroy or remove any persistent information relating to this ProviderInstance. This includes personalizations, subscription information and preferences.

Throws:

ProviderException

initSession

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

Called to initiate a session with a particular user. 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 providers running in a servlet environment, 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.

Parameters:

user - Current portal user.

externalApp - External Application information (if it exists).

Returns:

Array of cookie objects. In a servlet environment, these should be of class javax.servlet.http.Cookie. Alternatively, null can be returned if this provider doesn't use cookies or relies on the (user) session to maintain its state.

Throws:

ProviderException - if a generic provider error occurs.

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

getPortletDefinitions

public PortletDefinition[] getPortletDefinitions(int start,
                                                 int count,
                                                 boolean byUser,
                                                 ProviderUser user)
                                          throws ProviderException

Returns array of PortletDefinition objects for the portlets managed by this Provider. The range of definitions being requested is controlled by start and count. This method should return only count PortletDefinitions starting at start. If there are fewer then count definitions then a shorter array should be returned.

The PortletDefinitions returned by this method are constrained to those the user is authorized to access if byUser is true.

Parameters:

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

count - The maximum number of portlet definitions that should be returned.

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

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

Returns:

array of portlet definitions constrained to the indicated range.

Throws:

ProviderException

getPortletDefinitions

public PortletDefinition[] getPortletDefinitions(boolean byUser,
                                                 ProviderUser user)
                                          throws ProviderException

Returns an array of PortletDefinition objects for all of the portlets managed by this Provider. The PortletDefinitions returned by this method are constrained to those the user is authorized to access if byUser is true.

Parameters:

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

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

Returns:

array of portlet definitions constrained to the indicated range.

Throws:

ProviderException

getPortletDefinition

public PortletDefinition getPortletDefinition(long portletId,
                                              ProviderUser user)
                                       throws ProviderException

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

Parameters:

portletId - portlet Id.

user - Current user.

Returns:

the PortletDefinition associated with the given Id, or null if the user isn't authorized to access the portlet.

Throws:

ProviderException - if no PortletDefinition with the given id exists

getPortletDefinition

public PortletDefinition getPortletDefinition(long portletId,
                                              ProviderUser user,
                                              boolean securityCheck)
                                       throws ProviderException

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

Parameters:

portletId - portlet Id.

user - Current user.

securityCheck - controls whether or not an access check is performed.

Returns:

the PortletDefinition associated with the given Id. If the securityCheck parameter is true, and the user isn't authorized to access the portlet, null will be returned.

Throws:

ProviderException - if no PortletDefinition with the given id exists

getPortletInstance

public PortletInstance getPortletInstance(long portletId,
                                          java.lang.String portletInstanceName,
                                          ProviderUser user)
                                   throws ProviderException,
                                          PortletException

Deprecated. Use getPortletInstance(long, String, ProviderUser, PerfMonitor) instead.

Constructs a PortletInstance object based on the specified information. PortletInstance implements the behaviour of a specific instance of a portlet on a portal page.

This method uses the default locale specified on the PortletDefinition as the instance's default locale. Use getPortletInstance(long, String, ProviderUser, Locale) if the calling Portal has passed a default locale.

Parameters:

portletId - id of the portlet

portletInstanceName - instance name of the portlet on the portal page

user - the user who is accessing the portlet

Returns:

a new PortletInstance object based on the parameters passed

Throws:

ProviderException

PortletException

getPortletInstance

public PortletInstance getPortletInstance(long portletId,
                                          java.lang.String portletInstanceName,
                                          ProviderUser user,
                                          java.util.Locale defaultLocale)
                                   throws ProviderException,
                                          PortletException

Deprecated. Use getPortletInstance(long, String, ProviderUser, Locale, PerfMonitor) instead.

Constructs a PortletInstance object based on the specified information. PortletInstance implements the behaviour of a specific instance of a portlet on a portal page.

Parameters:

portletId - id of the portlet

portletInstanceName - instance name of the portlet on the portal page

user - the user who is accessing the portlet

defaultLocale - the instance's default locale, or null if the PortletDefinition's default locale is to be used.

Returns:

a new PortletInstance object based on the parameters passed

Throws:

ProviderException

PortletException

getPortletInstance

public PortletInstance getPortletInstance(long portletId,
                                          java.lang.String portletInstanceName,
                                          ProviderUser user,
                                          PerfMonitor monitor)
                                   throws ProviderException,
                                          PortletException

Constructs a PortletInstance object based on the specified information. PortletInstance implements the behaviour of a specific instance of a portlet on a portal page.

Parameters:

portletId - id of the portlet

portletInstanceName - instance name of the portlet on the portal page

user - the user who is accessing the portlet

monitor - the tracking object used to check the request execution time against the warning timeout specified in the provider properties.

Returns:

a new PortletInstance object based on the parameters passed

Throws:

ProviderException

PortletException

getPortletInstance

public PortletInstance getPortletInstance(long portletId,
                                          java.lang.String portletInstanceName,
                                          ProviderUser user,
                                          java.util.Locale defaultLocale,
                                          PerfMonitor monitor)
                                   throws ProviderException,
                                          PortletException

Constructs a PortletInstance object based on the specified information. PortletInstance implements the behaviour of a specific instance of a portlet on a portal page.

Parameters:

portletId - id of the portlet

portletInstanceName - instance name of the portlet on the portal page

user - the user who is accessing the portlet

defaultLocale - the instance's default locale, or null if the PortletDefinition's default locale is to be used.

monitor - the tracking object used to check the request execution time against the warning timeout specified in the provider properties.

Returns:

a new PortletInstance object based on the parameters passed

Throws:

ProviderException

PortletException

getPortletInstance

public PortletInstance getPortletInstance(long portletId,
                                          java.lang.String portletInstanceName,
                                          ProviderUser user,
                                          java.util.Locale defaultLocale,
                                          PerfMonitor monitor,
                                          boolean securityCheck)
                                   throws ProviderException,
                                          PortletException

Constructs a PortletInstance object based on the specified information. PortletInstance implements the behaviour of a specific instance of a portlet on a portal page.

Parameters:

portletId - id of the portlet

portletInstanceName - instance name of the portlet on the portal page

user - the user who is accessing the portlet

defaultLocale - the instance's default locale, or null if the PortletDefinition's default locale is to be used.

monitor - the tracking object used to check the request execution time against the warning timeout specified in the provider properties.

securityCheck - controls whether or not the PortletSecurityManager is queried for the user's access rights.

Returns:

a new PortletInstance object based on the parameters passed

Throws:

ProviderException

PortletException

getPreferenceStore

public PreferenceStore getPreferenceStore()
                                   throws PreferenceStoreException

Gets the default PreferenceStore that should be used by the ProviderInstance and all its child objects for which a preference store has not been chosen explicitly.

Returns:

the default preference store for this ProviderInstance

Throws:

PreferenceStoreException - if the ProviderInstance does not have a default preference store.

isDefinitionEqual

public boolean isDefinitionEqual(ProviderDefinition pd)

Compare the internal ProviderDefinition with that specified.

The ProviderLoader needs to be able to compare the internal definition of a ProviderInstance with it's own definition to determine if that instance needs to be replaced by a newer one.

Parameters:

pd - ProviderDefinition to compare to internal definition

Returns:

true if the ProviderDefinitions are the same, otherwise false.

getOidManager

public OidManager getOidManager()
                         throws ProviderException

Gets the OID Manager that provides access to the OID repository. The OID manager can be used to get access to user details.

Returns:

OidManager or null depending upon whether the OidManager has been configured.

Throws:

ProviderException

getCipherManager

public CipherManager getCipherManager()

Gets the the CipherManager which will be employed to encrypt exported data. A null value indicates that exported data will not be encrypted. The ProviderDefinition level cipher manager serves as the default for all contained portlets.

Returns:

the CipherManager which will be employed to encrypt exported data.

exportData

public byte[] exportData(boolean exportUsers,
                         java.lang.String[] userNames,
                         TransportLogger logger)
                  throws ProviderException

Exports provider level data from this ProviderInstance. If includeUsers is true, user specific data will be included for the set of users specified in userNames. Log messages may be included in the exported data set using the supplied TransportLogger.

Parameters:

exportUsers - speficies if the export data should contain user specifc data.

userNames - the set of users whose data should be exported. If null, data for all users will be included. If includeUsers is false, this parameter will be ignored.

logger - a TransportLogger which may be used for logging messages to be included with the exported data.

Returns:

a byte[] encapsulating all export worthy data, or null if there exists no data to export.

Throws:

ProviderException - if any non-recoverable error occurred while exporting the data.

importData

public void importData(byte[] data,
                       TransportLogger logger)
                throws ProviderException

Imports provider level data into this ProviderInstance, for example by updating an associated persistant store. Messages may be logged to the import initiator using the supplied TransportLogger

Parameters:

data - the data to import.

logger - a TransportLogger which can be used to log messages to the import initiator.

Throws:

ProviderException - if any non-recoverable error occurred while importing the data.

getContextPath

public java.lang.String getContextPath()

Returns a string which uniquely indentifies this ProviderInstance . Equivalent to getProviderId().