com.sun.portal.providers
Interface Provider

All Known Implementing Classes:

ProviderAdapter

public interface Provider

Provider defines the interface for implementing the provider component of a channel. Desktop channels consist of two major pieces; a provider object and its runtime configuration. A provider is the programmatic entity responsible for generating channels on the desktop. There is not necessarily a one-to-one mapping between providers and channels; a single provider can generate one or more channels depending on how it is configured.

A provider must implement this interface. Clients of the provider interface call these methods to query information about or to cause an action in the provider. Such clients include but are not limited to the Desktop servlet and other channels (container channels).

There are essentially two types of methods in this interface;

• methods that digest and compile markup. This includes getContent(), getEdit(), and processEdit().
• methods that query information about the content provider. This includes all methods that begin with get-(minus the get- methods).

The digest and compile type methods are passed in the HTTP request and response objects associated the HTTP request that caused the method to be called on the provider object. The semantics for the digest and compile methods are typically as follows: getContent() is used to return the channel's default view. The getEdit() method returns a form that allows the configuration of the channel to be modified (the "edit" view). Modifying this configuration will often but not necessarily affect the default channel view. The processEdit() method is typically used to process the form generated from the getEdit() method. Such uses of these methods is not required. Note: the request and response parameters are not the original objects that are passed by the web server to the desktop servlet. Rather, they are wrappers for those objects. There are certain methods on these objects that are not allowed from providers. These include:

HttpServletRequest

• getQueryString()
• getSession(boolean)
• isRequestedSessionIdFromCookie()
• isRequestedSessionIdFromUrl()
• isRequestedSessionIdValid()
• getContentLength()
• getInputStream()
• getParameter(String)
• getParameterNames()
• getParameterValues(String)
• getReader()

HttpServletResponse

• encodeRedirectUrl(String)
• encodeUrl(String)
• sendError(int)
• sendError(int, String)
• sendRedirect(String)
• setStatus(int)
• setStatus(int, String)
• getOutputStream()
• getWriter()
• setContentLength(int)
• setContentType(String)

If these methods are called, an UnsupportedOperationException is thrown.

Method Summary

StringBuffer	getContent(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Gets the provider's objects default view.
StringBuffer	getContent(Map m) Deprecated. Using this method has negative performance implications. Use getContent(HttpServletRequest, HttpServletResponse) instead.
String	getDescription() Gets the description of this provider.
StringBuffer	getEdit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Gets the edit view for the provider.
StringBuffer	getEdit(Map m) Deprecated. Using this method has negative performance implications. Use getEdit(HttpServletRequest, HttpServletResponse) instead.
int	getEditType() Gets the edit form type of the provider.
URL	getHelp(javax.servlet.http.HttpServletRequest req) Gets the help URL for this provider.
String	getName() Gets the name of this provider.
long	getRefreshTime() Gets the refresh time for this provider, in seconds.
String	getTitle() Gets the title of this provider.
int	getWidth() Gets the width of this provider.
void	init(String name, javax.servlet.http.HttpServletRequest req) Initializes the provider.
boolean	isEditable() This method determines if the provider has an edit view.
boolean	isPresentable() Determines if the provider is presentable based on the client device type.
URL	processEdit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Processes a form for this provider.
URL	processEdit(Map m) Deprecated. Using this method has negative performance implications. Use processEdit(HttpServletRequest, HttpServletResponse) instead.

Method Detail

init

public void init(String name,
                 javax.servlet.http.HttpServletRequest req)
          throws ProviderException

Initializes the provider.

This method must be called by clients of the provider object when the provider object is created (after it is constructed, or before the object is used). This method should not be called more than once per object.

Parameters:

name - Unique name identifying this provider. This value should always be returned from getName().

req - The HTTP request object corresponding to the HTTP request that caused this provider object to be created. This request may be used to extract session or user information that could be used to gain access to external resources.

Throws:

ProviderException - If there was an error initializing the provider. How this exception is handled is up to the client of the provider object.

See Also:

getName()

getContent

public StringBuffer getContent(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response)
                        throws ProviderException

Gets the provider's objects default view. This method is called by the clients of the provider object to request the provider's default view.

This method may return null if the provider does not implement a default view. In this case, the provider should return false from its isPresentable() method.

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

StringBuffer holding the content.

Throws:

ProviderException - If there was an error generating the content. How this exception is handled is up to the client of the provider object.

See Also:

ProviderException

getContent

public StringBuffer getContent(Map m)
                        throws ProviderException

Deprecated. Using this method has negative performance implications. Use getContent(HttpServletRequest, HttpServletResponse) instead.

Gets the provider's default view (alternate form).

The adapters for the Provider class (ProfileProviderAdapter and ProviderAdapter) call this method by default from the other getContent method. This method preserves backward compatibility for older providers and it offers a simpler interface than the one that passes in the request and response.

Parameters:

m - A key-value mapping of HTTP parameters passed to the desktop by the requesting browser.

Returns:

StringBuffer holding the html content.

Throws:

ProviderException - If there was an error generating the content. how this exception is handled is up to the client of the provider object.

See Also:

ProviderException

getEdit

public StringBuffer getEdit(javax.servlet.http.HttpServletRequest request,
                            javax.servlet.http.HttpServletResponse response)
                     throws ProviderException

Gets the edit view for the provider.

This method is called by the clients of the provider object to request the provider's edit view.

This method must generate either a complete document, or a subset, depending on the return value of .getEditType().

A subset document should include all code that goes between the FORM tags. The exception is that the submit and cancel buttons should not be generated. A subset document is always submitted back to the desktop servlet, where control is passed to the provider's processEdit() method for processing the form data.

If a complete document is returned, there are several restrictions:

• It must be a complete, valid form.
• The form must have an encoding type of "application/x-www-form-urlencoded".
• The form action must point back to the desktop servlet. Typically, this is "/ps/desktop".
• The form must specify a valid action to the desktop servlet as defined in the DesktopSerlvet javadocs.

The above restrictions only apply if the form is to be submitted to the desktop servlet. If the form is submitted to a third-party CGI or servlet, the format will depend on what this entity is expecting.

This method may return null if the provider does not implement an edit view. In this case, the provider should return false from its isEditable() method.

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

StringBuffer holding the html edit form.

Throws:

ProviderException - If there was an error generating the edit form. How this exception is handled is up to the client of the provider object.

See Also:

getContent(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), isEditable(), processEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), getEditType(), DesktopServlet, ProviderException

getEdit

public StringBuffer getEdit(Map m)
                     throws ProviderException

Deprecated. Using this method has negative performance implications. Use getEdit(HttpServletRequest, HttpServletResponse) instead.

Gets the edit view of the provider (alternate form).

The adapters for the Provider class (ProfileProviderAdapter and ProviderAdapter) call this method by default from the other getEdit() method. This method preserves backward compatibility for older providers and it offers a simpler interface than the one that passes in the request and response.

Parameters:

m - A key-value mapping of HTTP parameters passed to the desktop by the requesting browser.

Returns:

StringBuffer holding the html edit form.

Throws:

ProviderException - If there was an error generating the edit form. How this exception is handled is up to the client of the provider object.

getEditType

public int getEditType()
                throws UnknownEditTypeException

Gets the edit form type of the provider.

This method returns, and therefore defines, the edit form type for provider.

Returns:

The edit type; either EDIT_SUBSET or EDIT_COMPLETE

Throws:

UnknownEditTypeException - If an unknown or undefined edit type is encountered.

See Also:

getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), ProviderEditTypes

processEdit

public URL processEdit(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response)
                throws ProviderException

Processes a form for this provider.

This method is called to process form data associated with the provider. Typically, this method is called to process the edit page generated from the getEdit() method. Usually, the client calling this method on a provider object is the desktop servlet.

Form data, passed into this method in the request, has been decoded into Unicode.

When the desktop servlet receives a request where the action is "process", it looks at the parameters to identify which provider will handle the action, through this method. The request passed in contains the parameters.

After calling this method, the desktop servlet will re-direct to the URL returned from this method. Therefore, the result of a provider post can be any desktop serlvet action, or the content of an arbitrary URL. For more information on constructing desktop serlvet URLs, see DesktopSerlvet.

Parameters:

request - An HttpServletRequest that contains information related to this request for content.

response - An HttpServletResponse that allows the provider to influence the overall response for the desktop page (besides generating the content).

Returns:

The URL that the iPS desktop will re-direct to. A value of null should indicate to the client that it should return to its default view.

Throws:

ProviderException - If there was an error processing the edit form. How this exception is handled is up to the client of the provider object.

See Also:

getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), isEditable(), InvalidEditFormDataException, DesktopServlet

processEdit

public URL processEdit(Map m)
                throws ProviderException

Deprecated. Using this method has negative performance implications. Use processEdit(HttpServletRequest, HttpServletResponse) instead.

Processes the edit form for this provider (alternate form).

The adapters for the Provider class (ProfileProviderAdapter and ProviderAdapter) call this method by default from the other processEdit method. This method preserves backward compatibility for older providers and it offers a simpler interface than the one that passes in the request and response.

Parameters:

m - A key-value mapping of HTTP parameters passed to the desktop by the requesting browser as returned by the ServletRequest.parsePostData() method. Maps string keys to an array of strings values. For example, to access a parameter named "foo" in the map, do the following:

String bob = (String[])m.get("foo")[0];

Returns:

The URL that the iPS desktop will re-direct to. A value of null should indicate to the client that it should return to its default view.

See Also:

getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), isEditable(), InvalidEditFormDataException, DesktopServlet

isEditable

public boolean isEditable()
                   throws ProviderException

This method determines if the provider has an edit view.

Returns:

true or false, indicating if the provider has an edit view.

See Also:

getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), processEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

isPresentable

public boolean isPresentable()

Determines if the provider is presentable based on the client device type.

Returns:

true or false, indicating if the provider is presentable to the user's client device.

getTitle

public String getTitle()
                throws ProviderException

Gets the title of this provider.

Returns:

The title of this provider.

getName

public String getName()

Gets the name of this provider.

The name returned from this method must match the name of the provider that it was initialized with.

Returns:

The name of this provider.

getDescription

public String getDescription()
                      throws ProviderException

Gets the description of this provider.

Returns:

The description of this provider.

See Also:

init(java.lang.String, javax.servlet.http.HttpServletRequest)

getHelp

public URL getHelp(javax.servlet.http.HttpServletRequest req)
            throws ProviderException

Gets the help URL for this provider.

The returned help URL can be either fully-qualified URL string or a relative path. When it is relative path, the desktop software will prepend the server request string, plus the document root, plus the user locale to it to resolve the full URL.

Returns:

A URL pointing to the help page for the provider. A return value of null should signify that this provider does not have a help page.

getRefreshTime

public long getRefreshTime()
                    throws ProviderException

Gets the refresh time for this provider, in seconds.

Clients of the provider object should use this value to determine if they should fetch a fresh default view for the provider.

If the return value from this method is X, they may choose to not fetch fresh content (and use a cached copy instead) if less than X seconds has elapsed since the last time content was fetched.

If provider content is expected to change very infrequently, this method can return some value so that the provider's content is not fetched every time the front page is drawn, thereby saving significant processing time.

Clients may choose not to use this value.

Returns:

>0, refresh time in number of seconds that a container should wait before expiring a content cache. 0, container should never cache channel's content. -1, container may cache channel's content indefinitely.

getWidth

public int getWidth()
             throws ProviderException

Gets the width of this provider.

Clients of the provider object may call this method, allowing the channel to suggest how much / what type of screen real estate it requires. The return value of this method is only a suggestion, clients are free to interpret the return value or ignore it all together.

Returns:

The width of this provider, either WIDTH_THICK or WIDTH_THIN or WIDTH_FULL_TOP or WIDTH_FULL_BOTTOM.

Throws:

ProviderException - When there was an exception getting the width

See Also:

ProviderWidths.WIDTH_THIN, ProviderWidths.WIDTH_THICK, ProviderWidths.WIDTH_FULL_TOP, ProviderWidths.WIDTH_FULL_BOTTOM