3.7 Launching Tasks and Delegating to Tasks

An iManager task can launch another task in a separate window or delegate its area to another task. A task launched in a new window can close when the task returns. A delegate task takes over the area of the delegating task until the delegate task returns control to the delegating task, the parent, the fw.HomePage task, or any other task. For most situations, you will use task delegation.

3.7.1 The Launch Service and Launch Actions

The Launch service is a public service you can call to access the launch and delegation features from a URL. In the URL, you specify one of the following actions:

Launch

This action causes a task to appear in a new window. It has the following syntax:

 nps/servlet/portalservlet?NPService=LaunchService
 &NPAction=Launch
 &launch=serviceNameToLaunch
 &launcher=serviceIdOfLauncher&lifecycle={New | Reuse | Reset | Existing | Recreate}
 

Delegate

This action causes another task to take over the area of the task. It has the following syntax:

 nps/servlet/portalservlet?NPService=LaunchService
 &NPAction=Delegate
 &delegate=serviceNameToLaunch
 &launcher=serviceIdOfLauncher&lifecycle={New | Reuse | Reset | Existing | Recreate}
 

ReturnFromLaunch

This action causes a launched task to return. It has the following syntax:

 nps/servlet/portalservlet?NPService=LaunchService
 &NPAction=ReturnFromLaunch
 &returnID=serviceNameOfLaunchedService
 

ReturnFromDelegate

This action causes a delegate task to restore its area to a designated task. It has the following syntax:

 nps/servlet/portalservlet?NPService=LaunchService
 &NPAction=ReturnFromDelegate
 &returnID=serviceNameOfDelegateService
 

3.7.2 Life Cycles of Launched and Delegate Tasks

The Launch and Delegate actions require that you specify the life cycle of the launched or delegate task in the URL using the lifecycle parameter. The lifecycle parameter determines how the task instance is instantiated and freed. The following table describes the possible values of lifecycle:

Table 3-4 Possible lifecycle values

Value

Description

Code Name

Code Value

New

Creates a new instance with the name of the service appended to a four-digit random number.

LIFECYCLE_TYPE_NEW

1

Reuse

Like New, but uses a pool to reuse the tasks. (Must support Reset to use the pool.)

LIFECYCLE_TYPE_REUSE

2

Reset

Uses the name of the service but calls Reset on the task. (Must support Reset to use this.)

LIFECYCLE_TYPE_RESET

3

Existing

Uses the existing instance in its current state.

LIFECYCLE_TYPE_EXISTING

4

Recreate

Creates a new instance, and any existing instance is freed for garbage collection.

LIFECYCLE_TYPE_RECREATE

5

3.7.3 Accessing Launching and Delegation Features Programmatically

The com.novell.nps.gadgetManager.GadgetManager class provides the following methods for programmatic access to the launching and delegation features:

launchGadget

 public static GadgetInstance launchGadget(GadgetInstance launcher, PortalSession session, HttpServletRequest req, String launchServiceName, int delegationType) throws PortalException
 

delegateToGadget

 public static GadgetInstance delegateToGadget(GadgetInstance delegator, PortalSession session, HttpServletRequest req, String delegateServiceName, int delegationType) throws PortalException
 

returnToLauncher

 public static void returnToLauncher(GadgetInstance secondary, Object results, PortalSession session)
 

returnToDelegator

 public static void returnToDelegator(GadgetInstance secondary, Object results, PortalSession session)
 

3.7.4 Launching and Delegation Methods in GadgetInstance

The com.novell.emframe.dev.Task class implements the following methods of com.novell.nps.gadgetManager.GadgetInstance that support task launching and delegation by developers:

Methods Related to Launching or Delegating:

  • processSecondaryGadgetResults

Methods Related to Being Launched:

  • returnToPrimary

Life Cycle-Related Methods:

  • reset

  • release

  • getLifecycleType

3.7.5 Task Delegation Example

The JSP responsible for populating the Roles and Tasks frame uses task delegation. The task links set the target to the Content frame and cause the framework to delegate to the selected task and make the launcher the fw.HomePage task. The fw.HomePage task is not the task that delegates. Another task—the one responsible for populating the Roles and Tasks frame—is the delegating task. However, this task—the Roles and Tasks task—is setting up the delegation between the selected task and the fw.HomePage task.

For example, the Create User task has the following anchor tag:

 <a target="Content" href="frameservice?NPService=fw.LaunchService&NPAction=Delegate&delegate=base.CreateUser&launcher=fw.HomePage&lifecycle=Recreate">CreateUser</a>
 

Notice that this URL does not refer to the Roles and Tasks task. This is perfectly legal. Any task can launch any other task and designate any other task as the launcher.

Let's examine the elements of the URL specified in the anchor tag more closely:

 NPService=fw.LaunchService
 

To launch or delegate, everything must go through fw.LaunchService. (NPService= is similar to taskId=, as used in previous versions of iManager.)

 NPAction=Delegate
 

The value of NPAction can be either Delegate or Launch.

 delegate=base.CreateUser
 

This parameter specifies the task you want to run. If NPAction=Launch, then you would use launch=base.CreateUser instead to specify the task to run in the new window.

 launcher=fw.HomePage
 

With either NPAction=Delegate or NPAction=Launch, this parameter specifies which task is the parent task. When the delegate or launched task returns, control switches to the parent.

 lifecycle=Recreate
 

The lifecycle parameter specifies how to create or find an existing instance of the task. For launching, it is usually best to use Recreate. The possible values are listed in Section 3.7.2, Life Cycles of Launched and Delegate Tasks.

3.7.6 Closing the Window of a Launched Task

If you want your task started in a new window, and you want the window closed when the task returns, make fw.LaunchService the launcher. fw.LaunchService has code that closes the window if it is the parent. For example:

 <a target="_blank" href="frameservice?NPService=fw.LaunchService&NPAction=Launch&launch=Task1&launcher=fw.LaunchService&lifecycle=Recreate">Task2</a>
 

If you do not make fw.LaunchService the launcher, the launching task is responsible for closing the window. This might be desirable if the launching task needs to get results back from the launched task before closing the window itself or delegating to some other task.

3.7.7 More Examples

For another example of task delegation and launching, see the SDK_HOME\tomcat\webapps\nps\portal\modules\debug\skins\default\devices\default\TaskLaunchingDemo.jsp file.