Chapter 3 Overview of the Desktop Servlet

This chapter provides an overview of the DesktopServlet and discusses the relationship between the DesktopServlet and the PAPI. It provides information on how the DesktopServlet uses the various methods in the PAPI to perform the various actions (such as content, edit, process, and logout).

This chapter contains the following sections:

• Introduction to DesktopServlet

• DesktopServlet Actions

Introduction to DesktopServlet

The DesktopServlet coordinates the drawing of the Desktop, dispatches the process to the target channel based on the information stored in the underlining services, and validates the user with the Sun Java System Access Manager software.

In this sense, the DesktopServlet is a router of requests. It catches requests for content and processing, and passes them on to the specific provider object. Whenever a provider throws an exception that cannot be handled by the container provider, the exception will propagate all the way up to the DesktopServlet, and the DesktopServlet will display an error page.

For detailed information on how the DesktopServlet creates and validates a user session and creates and gets the provider context object, see the The Provider Life Cycle The following sections only describe how the DesktopServlet handles the various actions.

DesktopServlet Actions

The DesktopServlet understands several actions. Every action has an associated channel or container name and actions are performed on the associated channel or container. Actions are passed to the servlet via request parameters. The associated channel name is also passed as a parameter.

For example, to perform an action on a channel, pass in the following parameters to the servlet:

DesktopServletURL?action=actionType&provider=ChannelName

Here:

• action - indicates the type of action to take. Action can be content, edit, process, or logout.

• provider - indicates the name of the provider to contact. The provider argument is named that way for historical reasons; the value of the provider argument is really a channel or container name. If the provider parameter is absent or null in the request, the servlet assumes it is equal to the value of the last request. For the initial request, if the provider parameter is absent, then the defaultChannelName from the Desktop service will be used.

The action and provider parameters are not required; if they are absent, the default action is content, and provider is the value set in the Desktop service for the default channel.

The content, edit, and process actions map directly to method calls into the PAPI. For Desktop actions that map to PAPI method calls, the servlet passes an HTTP request and response object to the respective provider method. These objects are not the same objects passed into the servlet. The request and response objects passed to provider objects from the servlet are wrappers around the original request and response passed into the servlet. This is because there is certain functionality that is available from request and response objects that is not applicable to a provider. See the Javadocs for the Provider interface for more information.

The HTTP parameters in the original request object are processed before they are copied to the wrapper servlet request and response objects. As part of this processing, the parameters are decoded from the character set encoding used to represent the page into Unicode that is used in Java String objects. Therefore, the parameters that are passed to the providers are all stored as Unicode, and the provider does not have to do any decoding of its own related to the character encoding for the page.

Action content

When the action is content, the DesktopServlet gets the named channel’s main content. When the DesktopServlet receives a request where the action is content, to perform the content action on the channel, it takes the following parameters:

DesktopServletURL?action=content&provider=ChannelName[&last=false]

The content action maps directly to the following method calls in the PAPI: ProviderContext.getDefaultChannelName(), Provider.isPresentable(), and Provider.getContent().

The flowchart in Figure 2-5 on page 39 shows the various methods executed in the back end to process the content action. When the client makes a request for content (say after login), the DesktopServlet:

1. Determines the provider responsible for generating the requested content.

   If provider is null, it uses the default channel name (stored in the DefaultChannelName attribute) to get the provider. The default channel name is an Sun Java System Access Manager software attribute (DefaultChannelName) in the Desktop service, which is set to the topmost container that represents the whole Desktop view. The default channel name is set to the current target provider value when the request parameter last is set to false. If the provider is not null, the DesktopServlet gets the provider responsible from the HTTP parameter in the URL for generating the requested content.

2. Once the provider is determined, the provider’s isPresentable() method is invoked to determine if the provider can be presented to the requesting client.

   If the provider is determined to be not presentable, an error is thrown on the Desktop. If the provider can be presented, the provider’s getContent() method fetches the content for display on the client’s Desktop.

3. When last is set to false, the DesktopServlet will not set the last channel to the value of the provider parameter. If not specified, the default setting is last=true, and the last accessed channel is set to the value of the provider parameter.

   The next time when the action is content, the DesktopServlet provider parameter will be used to fetch the content. If the provider parameter is absent in the request URL, the DesktopServlet assumes it is equal to the value of the last request.

Figure 3–1 DesktopServlet content Action

Action edit

When the action is edit, the DesktopServlet gets the named channel’s or edit container’s request parameters and starts to process the edit action. When the DesktopServlet receives a request where the action is edit, to perform the edit action, it takes the following parameters:

DesktopServletURL?action=edit&provider=ChannelName for backward compatibility

Or,

DesktopServletURL?action=edit&provider=editContainer&targetprovider=ChannelName

The DesktopServlet checks the edit types based on the values defined in the ProviderEditTypes interface.

DesktopServlet Legacy edit Action

DesktopServletURL?action=edit&provider=ChannelName

The flowchart in Action edit shows the various methods executed in the back end to process the edit action. When the client makes a request to edit the channel’s editable parameters, the DesktopServlet:

1. Determines the provider responsible for generating the requested content.

   If provider is null, it uses the default channel name to get the provider. Last accessed channel is not assumed when action equals edit. Otherwise, the DesktopServlet gets the provider responsible specified in the URL.

2. Once the provider is determined, the channel’s isEditable() method is invoked to determine if the channel is editable.

   The DesktopServlet gets the named channel’s isEditable property. If the channel is determined to be not editable, an exception is thrown on the Desktop. If the channel can be edited, the DesktopServlet also checks the editType for that channel.

   The editType is a channel property that can be retrieved via the Provider.getEditType() method. The provider’s getEditType() method is invoked to determine the type of edit page to return on the Desktop.

3. If the channel’s edit type is:

   • EDIT_COMPLETE, the provider’s getEdit() method is invoked and the Edit page for the channel is returned on the Desktop.

   • EDIT_SUBSET, the edit container’s provider name will be detected (via the default Desktop Edit Container attribute), and then the edit container’s getEdit() method will be invoked. Also:

     The edit container’s provides a common look and feel of the edit page for all the channels that it contains. After it generates the markup for the common look and feel, it detects the channel name from the request parameter and determines whether the target channel is editable.

     If the target channel is not editable, it throws a provider exception. If the target channel is editable, it gets the channel’s edit type and delegates the process to the target channel’s getEdit() method.

   If the channel’s edit type is:

   • EDIT_COMPLETE, the Edit page is displayed.

   • EDIT_SUBSET, the edit container’s content is displayed and it wraps around the channel’s edit content.

Figure 3–2 DesktopServlet Legacy edit Action

DesktopServlet edit Action

DesktopServletURL?action=edit&provider=editContainer&targetprovider=ChannelName

The flowchart in Action edit shows the various methods executed in the back end to process the edit action. This flowchart shows how the DesktopServlet processes the edit action for a container. In this URL, the provider parameter specifies the edit container for the container, and the targetprovider parameter is the leaf channel inside the container. When the client makes a request to process this edit action, the DesktopServlet:

1. Determines the provider responsible for generating the requested content.

   If provider is null, it uses the default channel name to get the provider. Last accessed channel is not assumed when action equals edit. Otherwise, the DesktopServlet gets the provider responsible specified in the URL.

2. Once the provider is determined, the edit container’s isEditable() method is invoked to determine if the edit container is editable.

   The DesktopServlet gets the named edit container’s isEditable property. If the edit container is determined to be not editable, an exception is thrown on the Desktop. If the edit container can be edited, the DesktopServlet also checks the editType for that edit container.

   The editType is a property that can be retrieved via the Provider.getEditType() method. The provider’s getEditType() method is invoked to determine the type of edit page to return on the Desktop.

3. If the edit container’s edit type is:

   • EDIT_COMPLETE:

     • The edit container’s getEdit method is invoked and the leaf channel’s name is determined from the request parameter.

     • Once the leaf channel’s name is determined, the channel’s isEditable() method is invoked to determine if the channel is editable.

       If the channel is determined to be not editable, an exception is thrown on the Desktop. If the channel can be edited, the DesktopServlet also checks the editType for the leaf channel.

     • If the leaf channel’s edit type is:

       • EDIT_COMPLETE, the container calls the leaf channel’s getEdit() method and displays the edit page on the Desktop.

       • EDIT_SUBSET, the container calls the leaf channel’s getEdit() method and the container’s Edit Container wraps the leaf channel’s content before displaying the Edit page ont the Desktop.

         A container can define different edit container and the edit container name must be specified as well as the target channel name. The default Desktop edit container name is stored in the Access Manager as a Desktop service attribute.

   • EDIT_SUBSET, the Desktop servlet fetches the name of the edit container to use to wrap the channel’s edit page. The servlet fetches a handle to the edit container, and then calls the edit container’s getEdit() method. The edit container detects the original channel’s name from request parameters and calls getEdit() on that channel, and wraps the channel’s content before returning it to the servlet. See the legacy edit action for EDIT_SUBSET in Action edit for more information.

Figure 3–3 DesktopServlet edit Action

Action process

The process action allows the named channel to process URL parameters and form data, typically that of the channel’s edit form. When the DesktopServlet receives a request where the action is process, to perform the process action, it takes the following URL parameters:

DesktopServletURL?action=process&provider=channelName

Or,

DesktopServletURL?action=process&provider=editContainer&targetprovider=channelName

DesktopServlet Legacy process Action

DesktopServletURL?action=process&provider=channelName

When the DesktopServlet receives a request where the action is process (see Action process), the DesktopServlet:

1. Looks at the parameters to identify which provider will handle the action, through the provider’s processEdit() method.

   The processEdit() method is called to process the edit page generated from the getEdit() method. The request passed in contains the parameters.

2. Re-directs to the URL returned from the provider’s processEdit() method.

   If there is an InvalidEditFormDataException, the DesktopServlet will redirect the browser back to the channel’s edit page and include a URL parameter error so that the channel may display the cause of the exception to the user. That is, the DesktopServlet will get the error message and generate a new request as follows.

   DesktopServletURL?action=edit&provider=channelName&error=errormessage

Figure 3–4 DesktopServlet Legacy process Action

DesktopServlet process Action

DesktopServletURL?action=process&provider=editContainer&targetprovider=channelName

In this URL, the provider parameter specifies the edit container for the container, and the targetprovider parameter is the leaf channel inside the container. When the DesktopServlet receives a request where the action is process (see Action process), the DesktopServlet:

1. Determines whether the edit container is editable.

   If the edit container is not editable, an exception is thrown on the Desktop and control is returned to the web container. If the edit container is editable, it calls the edit container processEdit() method and determines the channel’s name from the request parameter.

2. Once the channel name is determined, it determines whether the channel is editable.

   If the channel is not editable, it throws a provider exception. If the channel is determined to be editable, it calls the channel’s processEdit() method.

3. Re-directs to the URL returned from the provider’s processEdit() method.

   If there is an InvalidEditFormDataException, the DesktopServlet will redirect the browser back to the channel’s edit page and include a URL parameter error so that the channel may display the cause of the exception to the user. That is, the DesktopServlet will get the error message and generate a new request as follows:

   DesktopServletURL?action=edit&provider=channelName&error=errormessage

   If there is no InvalidEditFormDataException, the DesktopServlet generates the new URL and returns control to the web container.

Figure 3–5 DesktopServlet process Action

Action logout

The logout action ends the user session. When the DesktopServlet receives a request where the action is logout, to perform the logout action, it takes the following parameters:

DesktopServletURL/dt?action=logout

When the DesktopServlet receives a request for the logout action, it redirects the browser to a URL defined by the Access Manager software iplanet-am-platform-logout-url attribute in the Platform service. By default, this attribute has the value /amserver/logout. But, If this is set to something that does not terminate the user’s session, such as a static HTML page, then /portal/dt?action=logout will not terminate the user session.