oracle.portal.provider.v2
Class PortletInstance

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

Direct Known Subclasses:

DefaultPortletInstance

public abstract class PortletInstance
extends java.lang.Object

A PortletInstance is the entity that carries out the responsibilities of a single 'instance' of a portlet on a single Portal page. Generally, a PortletInstance is driven by meta data information in a PortletDefinition that may be shared with other PortletInstances, perhaps on the same page or other Portal pages.

Constructor Summary

PortletInstance()

Method Summary

void	copyTo(ProviderUser user, PortletInstance dest) Called when the portlet instance is copied to another page.
void	deregister(ProviderUser user) Called when the portlet instance is removed from the page.
byte[]	exportData(boolean exportUsers, java.lang.String[] userNames, TransportLogger logger) Exports portlet instance level data contained by the PreferenceStore returned by getPreferenceStore() from this PortletInstance.
java.lang.String	getActionParameterName() Retrieves the name of the parameter to contain the name of the 'action' submitted by the customize form of this portlet instance.
CipherManager	getCipherManager() Gets the the CipherManager which will be employed to encrypt exported data and decrypt imported data.
java.lang.String	getContextPath() Returns a string which uniquely indentifies this PortletInstance
java.util.Locale	getDefaultLocale() Gets the default Locale that should be used on behalf of this instance.
java.lang.Object	getEditData(ProviderUser user, java.util.Locale locale, RenderContext rc) Retrieves an object containing the customizable data for the given user in the given locale within the given context.
java.lang.Object	getEditDefaultData(java.util.Locale locale, RenderContext rc) Retrieves an object containing the default data for the PortletInstance in the given locale.
java.lang.String	getInstanceName() Gets the Portal generated name of this PortletInstance.
PortletDefinition	getPortletDefinition() Gets the PortletDefinition which this PortletInstance is an instance of.
long	getPortletId() Gets the ID of the PortletDefinition which this PortletInstance is an instance of.
PreferenceStore	getPreferenceStore() Gets the default PreferenceStore that should be used by the PortletInstance and all its child objects for which a preference store has not been chosen explicitly.
java.lang.String	getProviderId() Gets the ID of the ProviderInstance which owns this PortletInstance.
ProviderInstance	getProviderInstance() Gets the ProviderInstance which owns this PortletInstance.
java.lang.String	getShortTitle(ProviderUser user, java.util.Locale locale, RenderContext rc) Retrieves the short title for the PortletInstance.
java.lang.String	getTitle(ProviderUser user, java.util.Locale locale, RenderContext rc) Retrieves the title for the PortletInstance.
boolean	hasAccess(ProviderUser user, java.util.Locale locale) Verifies whether the user is authorized to use this particular portlet instance.
boolean	hasTimeoutElapsed() Returns boolean indicating whether the warning timeout for a request has elapsed.
void	importData(byte[] data, TransportLogger logger) Imports portlet instance level data into this PortletInstance, for example by updating an associated persistant store.
void	init(ProviderInstance providerInstance, PortletDefinition portletDefinition, java.lang.String instanceName, java.util.Locale defLocale) Deprecated. Replaced by init(ProviderInstance, PortletDefinition, String, Locale, PerfMonitor)
void	init(ProviderInstance providerInstance, PortletDefinition portletDefinition, java.lang.String instanceName, java.util.Locale defLocale, PerfMonitor monitor) Initialize the portlet instance after construction.
void	register(ProviderUser user) Called when the portlet instance is first created on a page.
abstract void	render(ProviderUser user, java.util.Locale locale, RenderContext rc) Renders a visual representation of this portlet instance for the given user in the given locale in the given context.
void	submitEditData(ProviderUser user, java.util.Locale locale, RenderContext rc, java.lang.Object o) Stores an object containing the customizable data for the given user in the given locale within the given context.

Methods inherited from class java.lang.Object

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

Constructor Detail

PortletInstance

public PortletInstance()

Method Detail

init

public void init(ProviderInstance providerInstance,
                 PortletDefinition portletDefinition,
                 java.lang.String instanceName,
                 java.util.Locale defLocale)
          throws PortletException

Deprecated. Replaced by init(ProviderInstance, PortletDefinition, String, Locale, PerfMonitor)

Initialize the portlet instance after construction.

Parameters:

providerInstance - Provider of this instance

portletDefinition - definition of this instance

instanceName - Portal generated name of this instance

defLocale - the default language/locale setting of the portal, if available, or null if the default locale defined on the PortletDefinition should be used.

Throws:

PortletException - if an error occurs during initialization.

init

public void init(ProviderInstance providerInstance,
                 PortletDefinition portletDefinition,
                 java.lang.String instanceName,
                 java.util.Locale defLocale,
                 PerfMonitor monitor)
          throws PortletException

Initialize the portlet instance after construction.

Parameters:

providerInstance - Provider of this instance

portletDefinition - definition of this instance

instanceName - Portal generated name of this instance

defLocale - the default language/locale setting of the portal, if available, or null if the default locale defined on the PortletDefinition should be used.

monitor - used to track the request execution progress against the timeouts defined in the provider properties.

Throws:

PortletException - if an error occurs during initialization.

getProviderInstance

public ProviderInstance getProviderInstance()

Gets the ProviderInstance which owns this PortletInstance.

Returns:

the ProviderInstance which owns this PortletInstance.

getProviderId

public java.lang.String getProviderId()

Gets the ID of the ProviderInstance which owns this PortletInstance. This is a convenience method for calling getProviderInstance().getProviderId().

Returns:

the ID of the ProviderInstance which owns this PortletInstance.

getPortletDefinition

public PortletDefinition getPortletDefinition()

Gets the PortletDefinition which this PortletInstance is an instance of.

Returns:

the PortletDefinition which this PortletInstance is an instance of.

getPortletId

public long getPortletId()

Gets the ID of the PortletDefinition which this PortletInstance is an instance of. This is a convenience method for calling getPortletDefinition().getId().

Returns:

the ID of the PortletDefinition which this PortletInstance is an instance of.

getInstanceName

public java.lang.String getInstanceName()

Gets the Portal generated name of this PortletInstance.

Returns:

the Portal generated name of this PortletInstance.

getDefaultLocale

public java.util.Locale getDefaultLocale()

Gets the default Locale that should be used on behalf of this instance. This is generally the Portal's default locale. However if not set / passed by the portal then it is the default locale of the PortletDefinition.

Returns:

the default Locale that should be used on behalf of this instance.

See Also:

PortletDefinition.getDefaultLocale()

getActionParameterName

public java.lang.String getActionParameterName()

Retrieves the name of the parameter to contain the name of the 'action' submitted by the customize form of this portlet instance.

Returns:

action parameter name.

getPreferenceStore

public PreferenceStore getPreferenceStore()
                                   throws PreferenceStoreException

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

Returns:

the default preference store for this PortletInstance

Throws:

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

register

public void register(ProviderUser user)
              throws java.io.IOException,
                     PortletAlreadyExistsException,
                     AccessControlException

Called when the portlet instance is first created on a page. This gives the PortletInstance the opportunity to initialize defaults for persisted customization data. This default implementation does nothing. Subclasses should override.

Parameters:

user - the user performing this operation.

Throws:

java.io.IOException - if an I/O error occurs whilst accessing persistent storage.

PortletAlreadyExistsException - if this instance has already been registered.

AccessControlException - if the given user isn't authorized to access this instance.

deregister

public void deregister(ProviderUser user)
                throws java.io.IOException,
                       PortletNotFoundException,
                       AccessControlException

Called when the portlet instance is removed from the page. This gives the PortletInstance the opportunity to remove any persisted customization data. This default implementation does nothing. Subclasses should override.

Parameters:

user - the user performing this operation.

Throws:

java.io.IOException - if an I/O error occurs whilst accessing persistent storage.

PortletNotFoundException - if this instance isn't known to exist in the Portal, i.e. hasn't been registered.

AccessControlException - if the given user isn't authorized to access this instance.

copyTo

public void copyTo(ProviderUser user,
                   PortletInstance dest)
            throws java.io.IOException,
                   PortletNotFoundException,
                   AccessControlException

Called when the portlet instance is copied to another page. This gives the PortletInstance the opportunity to export defaults for persisted customization data to the new instance. This default implementation does nothing. Subclasses should override.

Parameters:

user - the user performing this operation.

dest - the PortletInstance to export data to.

Throws:

java.io.IOException - if an I/O error occurs whilst accessing persistent storage.

PortletNotFoundException - if this instance or the destination instance isn't known to exist in the Portal, i.e. hasn't been registered.

AccessControlException - if the given user isn't authorized to access this instance or the destination instance.

hasAccess

public boolean hasAccess(ProviderUser user,
                         java.util.Locale locale)
                  throws PortletNotFoundException

Verifies whether the user is authorized to use this particular portlet instance.

Parameters:

user - the current user we are being asked to authorize.

locale - the language setting with which the user has logged on to portal.

Returns:

true if the user is authorized to access this portlet instance. This default implementation always returns true. Subclasses should override.

Throws:

PortletNotFoundException - if this instance isn't known to exist in the Portal, i.e. hasn't been registered.

getEditData

public java.lang.Object getEditData(ProviderUser user,
                                    java.util.Locale locale,
                                    RenderContext rc)
                             throws java.io.IOException,
                                    PortletNotFoundException,
                                    AccessControlException

Retrieves an object containing the customizable data for the given user in the given locale within the given context. If the context is "Edit Defaults" mode, the data should correspond to the defaults for that locale, rather than the data for that specific user.

Parameters:

user - the user for whom the data is being retrieved.

locale - the language setting with which the user has logged on to portal.

rc - an object describing the context in which this PortletInstance is being rendered.

Returns:

an object containing the customizable data for the given user in the given locale within the given context, or null if none exists. This default implementation always returns null. Subclasses should override.

Throws:

java.io.IOException - if an I/O error occurs whilst retrieving the data

PortletNotFoundException - if this instance isn't known to exist in the Portal, i.e. hasn't been registered.

AccessControlException - if the given user isn't authorized to access this instance.

getEditDefaultData

public java.lang.Object getEditDefaultData(java.util.Locale locale,
                                           RenderContext rc)
                                    throws java.io.IOException,
                                           PortletNotFoundException,
                                           AccessControlException

Retrieves an object containing the default data for the PortletInstance in the given locale.

Parameters:

locale - the language setting with which the user has logged on to Portal.

rc - an object describing the context in which this PortletInstance is being rendered.

Returns:

an object containing the default data for the PortletInstance in the given locale within the given context, or null if none exists. This default implementation always returns null. Subclasses should override.

Throws:

java.io.IOException - if an I/O error occurs whilst retrieving the data

PortletNotFoundException - if this instance isn't known to exist in the Portal, i.e. hasn't been registered.

AccessControlException - if the given user isn't authorized to access this instance.

submitEditData

public void submitEditData(ProviderUser user,
                           java.util.Locale locale,
                           RenderContext rc,
                           java.lang.Object o)
                    throws java.io.IOException,
                           AccessControlException

Stores an object containing the customizable data for the given user in the given locale within the given context. If the context is "Edit Defaults" mode, the data should be stored as the defaults for that locale, rather than the data for that specific user. This default implementation does nothing. Subclasses should override.

Parameters:

user - the user for whom the data is being stored.

locale - the language setting with which the user has logged on to portal.

rc - an object describing the context in which this PortletInstance is being rendered.

o - an object containing the customizable data for the given user in the given locale within the given context.

Throws:

java.io.IOException - if an I/O error occurs whilst retrieving the data

AccessControlException - if the given user isn't authorized to access this instance.

render

public abstract void render(ProviderUser user,
                            java.util.Locale locale,
                            RenderContext rc)
                     throws AccessControlException,
                            PortletException

Renders a visual representation of this portlet instance for the given user in the given locale in the given context. Subclasses must define.

Parameters:

user - the user for whom this PortletInstance is being rendered.

locale - the language setting with which the user has logged on to portal.

rc - an object describing the context in which this PortletInstance is being rendered.

Throws:

AccessControlException - if the given user isn't authorized to access this instance.

PortletException - if a general portlet exception occurs whilst rendering.

hasTimeoutElapsed

public boolean hasTimeoutElapsed()

Returns boolean indicating whether the warning timeout for a request has elapsed.

Returns:

true if the warning timeout has elapsed.

getTitle

public java.lang.String getTitle(ProviderUser user,
                                 java.util.Locale locale,
                                 RenderContext rc)
                          throws AccessControlException

Retrieves the title for the PortletInstance. If this portlet provides personalization via the NameValuePersonalizationObject class, the customized title is returned. If no customized title can be found, the title declared in the PortletDefinition is returned.

Parameters:

user - the ProviderUser for whom the portlet is being called.

locale - the java.util.Locale of the user.

rc - the RenderContext.

Throws:

AccessControlException

getShortTitle

public java.lang.String getShortTitle(ProviderUser user,
                                      java.util.Locale locale,
                                      RenderContext rc)
                               throws AccessControlException

Retrieves the short title for the PortletInstance. If this portlet provides personalization via the NameValuePersonalizationObject class, the customized short title is returned. If no customized short title can be found, the short title declared in the PortletDefinition is returned.

Parameters:

user - the ProviderUser for whom the portlet is being called.

locale - the java.util.Locale of the user.

rc - the RenderContext.

Throws:

AccessControlException

exportData

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

Exports portlet instance level data contained by the PreferenceStore returned by getPreferenceStore() from this PortletInstance. 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:

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

importData

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

Imports portlet instance level data into this PortletInstance, 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:

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

getContextPath

public java.lang.String getContextPath()

Returns a string which uniquely indentifies this PortletInstance

getCipherManager

public CipherManager getCipherManager()

Gets the the CipherManager which will be employed to encrypt exported data and decrypt imported data. A null value indicates that exported data will not be encrypted. The PortletDefinition level cipher manager overides any set at ProviderDefinition level.

Returns:

the CipherManager which will be employed to encrypt exported data and decrypt imported data.