com.iplanet.portalserver.providers
Interface Provider

All Known Implementing Classes:

ProviderAdapter

public interface Provider

Provider defines the interface for implementing Content Providers (provider).

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 content provider must implement this interface. The desktop calls these methods to query information about or to cause an action in the provider.

There are essentially three types of methods in this interface;

• methods that digest and compile html. 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).
• methods that set information in the provider. This includes all set- methods. When a new user logs in, the desktop constructs all of the providers that the user has configured, and calls init() on each of them. This is done only once per user session.

  See Also:

  ProfileProviderAdapter, ProviderAdapter

  Field Summary

  static int	EDIT_COMPLETE Edit page is a complete HTML document.
  static int	EDIT_SUBSET Edit page is not a complete HTML document.
  static int	WIDTH_FULL_BOTTOM Provider can be displayed in a "full" frame at the bottom.
  static int	WIDTH_FULL_TOP Provider can be displayed in a "full" frame at the top.
  static int	WIDTH_THICK Provider can be displayed in a "thick" frame.
  static int	WIDTH_THIN Provider can be displayed in a "thin" frame.

  Method Summary

  java.lang.String	getBackgroundColor() Get the background color for this provider.
  int	getColumn() Get the column in which this provider should be displayed in.
  java.lang.StringBuffer	getContent(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Get the provider's content.
  java.lang.StringBuffer	getContent(java.util.Map m) Get the provider's content (alternate form).
  java.lang.String	getDescription() Get the description of this provider.
  java.lang.StringBuffer	getEdit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Get the edit page of the provider.
  java.lang.StringBuffer	getEdit(java.util.Map m) Get the edit page of the provider (alternate form).
  int	getEditType() Get the edit form type of the provider.
  java.net.URL	getHelp() Get the help link for this provider.
  java.lang.String	getName() Get the name of this provider.
  long	getRefreshTime() Get the refresh time for this provider, in seconds.
  int	getRow() Get the row in which this provider should be displayed in.
  java.lang.String	getTitle() Get the title of this provider.
  int	getWidth() Get the width of this provider.
  boolean	hasBorder() Should this provider have a border drawn around it? The desktop calls this method when the front page is drawn.
  boolean	hasFrame() Should this provider have a window frame around it? A frame is defined as the "window" frame containing a title and channel controls that surround provider content.
  boolean	hasHelp() Determine if the provider has a help page associated with it.
  void	init(java.lang.String name, Session session) Initializes the provider.
  boolean	isDetachable() Determine if the provider can be detached from the Desktop.
  boolean	isDetached() Determine if the provider is detached from the Desktop.
  boolean	isEditable() Determine if the provider has an edit page.
  boolean	isMinimizable() Determine if the provider can be minimized on the Desktop.
  boolean	isMinimized() Determine if the provider is minimized on the Desktop.
  boolean	isMovable() Determine if the user can move this channel around on the desktop This method is called by the desktop when the user attempts to change the layout to see if they are allowed to move said channels.
  boolean	isPresentable() Determine if the provider is presentable based on the client device type.
  boolean	isRemovable() Determine if the user can remove this provider from the desktop This method is called by the desktop when it draws the front page.
  void	load() Load persistently stored attributes for this provider.
  java.net.URL	processEdit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Process the edit form for this provider.
  java.net.URL	processEdit(java.util.Map m)
  int	setColumn(int column) Sets the column for this provider to be displayed in.
  boolean	setDetached(boolean detached) Set the detached state of this provider.
  boolean	setMinimized(boolean minimized) Set the minimized state of this provider.
  int	setRow(int row) Sets the row for this provider to be displayed in.
  void	store() Persistently store attributes for this provider.

  Field Detail

  WIDTH_THICK

  public static final int WIDTH_THICK

  Provider can be displayed in a "thick" frame.

  WIDTH_THIN

  public static final int WIDTH_THIN

  Provider can be displayed in a "thin" frame.

  WIDTH_FULL_TOP

  public static final int WIDTH_FULL_TOP

  Provider can be displayed in a "full" frame at the top.

  WIDTH_FULL_BOTTOM

  public static final int WIDTH_FULL_BOTTOM

  Provider can be displayed in a "full" frame at the bottom.

  EDIT_SUBSET

  public static final int EDIT_SUBSET

  Edit page is not a complete HTML document. This value is potentially returned from .getEdit() to signify that the buffer returned is only a subset of an HTML document.

  See Also:

  EDIT_COMPLETE, getEditType(), getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

  EDIT_COMPLETE

  public static final int EDIT_COMPLETE

  Edit page is a complete HTML document. This value is potentially returned from .getEdit() to signify that the buffer returned is a complete HTML document.

  See Also:

  EDIT_SUBSET, getEditType(), getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

  Method Detail

  init

  public void init(java.lang.String name,
                   Session session)
            throws ProviderException

  Initializes the provider. This method is called by the desktop when a new user session is created; it is called only one per user session.

  Parameters:

  session - The Session object corresponding to the request received by the desktop. This object allows the provider to query the webtop profile service for information about itself or the user who initiated the request. This parameter can be ignored if your provider does not query the profile service.

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

  Throws:

  ProviderException - If there was an error initializing the provider.

  See Also:

  getName()

  getContent

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

  Get the provider's content. This method is called by the desktop when a request is made for the provider's content. This could be when the front page is drawn, when a detached provider is refreshed, or when a direct request for the provider's content is received.

  Note: the request and response parameters are not the objects that passed by the web server to the DesktopServlet. 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.

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

  Throws:

  ProviderException - If there was an error generating the content. Upon catching this error, the desktop application will attempt to fetch a cached copy of the content. If a cached copy does not exist, then an error message will be displayed in the body of the provider.

  ProviderException - If there was an error getting provider content.

  See Also:

  ProviderException

  getContent

  public java.lang.StringBuffer getContent(java.util.Map m)
                                    throws ProviderException

  Get the provider's content (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 GET 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. Upon catching this error, the desktop application will attempt to fetch a cached copy of the content. If a cached copy does not exist, then an error message will be displayed in the body of the provider.

  ProviderException - If there was an error getting provider content.

  See Also:

  ProviderException

  getEdit

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

  Get the edit page of the provider. This method is called when the Desktop receives a request for the provider's edit page. This happens when the user clicks on the provider's "Edit" button, or when the desktop receives a direct request for the provider's edit page.

  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 method must be POST.
  • The form must have an encoding type of "application/x-www-form-urlencoded".
  • The form action must be "/DesktopServlet".
  • The form must specify a valid action to the desktop servlet as defined in the DesktopURL 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.

  Note: The same restrictions apply to the arguments for this method as for the arguments of the getContent method that takes a request and response.

  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. The desktop does not do anything special if it catches this exception; it will display an error page.

  See Also:

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

  getEdit

  public java.lang.StringBuffer getEdit(java.util.Map m)
                                 throws ProviderException

  Get the edit page 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 GET 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. The desktop does not do anything special if it catches this exception; it will display an error page.

  getEditType

  public int getEditType()
                  throws UnknownEditTypeException

  Get the edit form type of the provider. This method returns, and therefore defines, the edit for type that must be returned from .getEdit().

  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), EDIT_SUBSET, EDIT_COMPLETE

  processEdit

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

  Process the edit form for this provider. This method is called when the the provider's edit page is submitted, or when the desktop receives a direct request for this provider to process post data.

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

  When the iPS desktop receives a POST request, it looks at the parameters to identify which provider will handle the post, through this method. The request passed in contains the parameters.

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

  Note: The same restrictions apply to the arguments for this method as for the arguments of the getContent method that takes a request and response.

  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 processing the edit form. The desktop application catches all such exceptions from this method. The text of the exception (from its getMessage() method) is inserted in the resulting content as an inline error. An exception of type InvalidEditFormData causes the desktop to re-display the provider's edit page, otherwise, the front page is returned.

  See Also:

  getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), isEditable(), com.iplanet.portalserver.providers.InvalidEditFormData, DesktopURL

  processEdit

  public java.net.URL processEdit(java.util.Map m)
                           throws ProviderException

  isEditable

  public boolean isEditable()

  Determine if the provider has an edit page. This method is called by the desktop when it draws the front page.

  Returns:

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

  See Also:

  getEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), processEdit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), com.iplanet.portalserver.desktop.util.DtConstants

  isPresentable

  public boolean isPresentable()

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

  hasHelp

  public boolean hasHelp()

  Determine if the provider has a help page associated with it. This method is called by the desktop when it draws the front page.

  Returns:

  true if this provider has an help page, otherwise false

  isDetachable

  public boolean isDetachable()

  Determine if the provider can be detached from the Desktop. This method is called by the desktop when it draws the front page.

  Returns:

  true if this provider can be detached, otherwise false

  See Also:

  isDetached(), setDetached(boolean)

  isMinimizable

  public boolean isMinimizable()

  Determine if the provider can be minimized on the Desktop. If the provider ever returns true from this method, then it must persistently store the detached state. This method is called by the desktop when it draws the front page.

  Returns:

  true if this provider can be minimized, otherwise false

  See Also:

  isMinimized(), setMinimized(boolean)

  isRemovable

  public boolean isRemovable()

  Determine if the user can remove this provider from the desktop This method is called by the desktop when it draws the front page.

  Returns:

  true if this provider can be removed otherwise false

  isMovable

  public boolean isMovable()

  Determine if the user can move this channel around on the desktop This method is called by the desktop when the user attempts to change the layout to see if they are allowed to move said channels.

  Returns:

  true if this provider is movable. otherwise false

  setDetached

  public boolean setDetached(boolean detached)

  Set the detached state of this provider. If a provider is "detached", it is displayed in a separate browser window by the desktop.

  This method is called by the desktop when the user chooses to detach this provider.

  Parameters:

  detached - whether the provider is detached or not.

  Returns:

  the previous state.

  See Also:

  isDetached(), isDetachable()

  isDetached

  public boolean isDetached()

  Determine if the provider is detached from the Desktop. If the provider ever returns true from the isDetachable() method, then is must then persistently store the detached state.

  The desktop calls this method when the front page is drawn.

  Returns:

  true if this provider is detached, otherwise false

  See Also:

  isDetachable(), setDetached(boolean)

  isMinimized

  public boolean isMinimized()

  Determine if the provider is minimized on the Desktop. If the provider ever returns true from isMinimizable(), it must then persistently store the minimized state. The desktop calls this method when the front page is drawn.

  Returns:

  true if this provider is minimized, otherwise false

  See Also:

  isMinimizable(), setMinimized(boolean)

  getTitle

  public java.lang.String getTitle()

  Get the title of this provider. The desktop calls this method when the front page is drawn, and when the user selects the content page.

  Returns:

  The title of this provider.

  getName

  public java.lang.String getName()

  Get the name of this provider. The name returned from this mathod must match the name of the provider which was entered into the desktop profile.

  Returns:

  The name of this provider.

  getDescription

  public java.lang.String getDescription()

  Get the description of this provider. The desktop calls this method when the user selects the content page.

  Returns:

  The description of this provider.

  See Also:

  init(java.lang.String, com.iplanet.portalserver.session.Session)

  getBackgroundColor

  public java.lang.String getBackgroundColor()

  Get the background color for this provider.

  Returns:

  the HTML-compliant background color for this provider. e.g., "WHITE", "#DDDDDD", etc.

  hasBorder

  public boolean hasBorder()

  Should this provider have a border drawn around it? The desktop calls this method when the front page is drawn.

  Returns:

  a boolean indicating whether the provider should be drawn with a border.

  hasFrame

  public boolean hasFrame()

  Should this provider have a window frame around it? A frame is defined as the "window" frame containing a title and channel controls that surround provider content. The desktop calls this method when the front page is drwan.

  Returns:

  a boolean indicating whether the provider should be drawn with a window frame.

  getWidth

  public int getWidth()

  Get the width of this provider. The desktop calls this method when the front page is drawn, when the layout page is drawn, and when the content page is drawn.

  Returns:

  The width of this provider, either WIDTH_THICK or WIDTH_THIN.

  See Also:

  WIDTH_THIN, WIDTH_THICK

  getColumn

  public int getColumn()

  Get the column in which this provider should be displayed in. The desktop calls this method when the front page is drawn, and when the layout page is drawn.

  Returns:

  the column for this provider; either "1", "2", or "3".

  See Also:

  setColumn(int)

  getRow

  public int getRow()

  Get the row in which this provider should be displayed in. this controls the horizontal position within the channel's column. The desktop calls this method when the front page is drawn, and when the layout page is drawn.

  Returns:

  the row for this provider; "1", "2",....

  getHelp

  public java.net.URL getHelp()

  Get the help link for this provider. The desktop calls this method when the front page is drawn.

  Returns:

  A URL pointing to the help page for the provider.

  See Also:

  hasHelp()

  setMinimized

  public boolean setMinimized(boolean minimized)

  Set the minimized state of this provider. If a provider is minimized, only its title bar is display on the desktop.

  The desktop calls this method when the user chooses to minimize a channel drawn by this provider.

  Parameters:

  minimized - whether the provider is minimized or not.

  Returns:

  the old state.

  See Also:

  isMinimizable(), isMinimized()

  setColumn

  public int setColumn(int column)

  Sets the column for this provider to be displayed in. Either 1, 2, or 3. The desktop calls this method when the user changes the provider's display column from the layout page.

  Parameters:

  column - The new column.

  Returns:

  The previous column.

  See Also:

  getColumn()

  setRow

  public int setRow(int row)

  Sets the row for this provider to be displayed in. Either 1, 2.... The desktop calls this method when the user changes the provider's display column from the layout page.

  Parameters:

  row - The new row.

  Returns:

  The Previous row.

  See Also:

  getRow()

  load

  public void load()
            throws ProviderException

  Load persistently stored attributes for this provider. The desktop calls this method once when a new user session is created.

  Throws:

  ProviderException - If there was an error loading the persistent data for this provider. If the desktop catches this exception, nothing special is done; an error page is displayed.

  store

  public void store()
             throws ProviderException

  Persistently store attributes for this provider. The desktop calls this method when a user logs out, or when the desktop receives a specific request to store the user configuration.

  Throws:

  ProviderException - If there was an error storing the persistent data for this provider. If the desktop catches this exception, nothing special is done; an error page is displayed.

  getRefreshTime

  public long getRefreshTime()

  Get the refresh time for this provider, in seconds. When the desktop fetches the content for a channel, it first checks to see whether the refresh time has expired; it checks if the difference between the current time and the time when the channel's content was last cached is greater than the value returned from this method.

  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.

  Returns:

  the number of seconds the desktop should wait before attempting to fetch fresh content for the channel(s) drawn by this provider. A value of 0 instructs the desktop to never cache content for channels generated by this provider.