Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `ProviderInstance`s 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.
`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[]` | `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, 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` | `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.

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.

### 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 `PortletDefinition`s 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:
    `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:
    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.

### 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 `PortletDefinition`s 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.

### 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 `PortletDefinition`s 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.

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

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

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

### 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
    `tracker` - 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

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

### 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 `ProviderDefinition`s 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2002, Oracle Corporation. All Rights Reserved.