com.novell.emframe.dev
Class Task

java.lang.Object
  com.novell.nps.gadgetManager.BaseGadgetInstance
      com.novell.emframe.dev.Task

All Implemented Interfaces:

com.novell.nps.configManager.ConfigurationComplete, com.novell.nps.gadgetManager.GadgetInstance, java.io.Serializable

Direct Known Subclasses:

eDirAccessService, EmptyTask, PropertyBook, VetoCreatorTask

public abstract class Task

extends com.novell.nps.gadgetManager.BaseGadgetInstance

This is the main class your Task will want to extend to plug-in to the iManager framework. You must implement the public abstract boolean execute(TaskContext context, Properties resultStrings); method. Do not use any other execute method as they have all been deprecated and are only around for backwards compatibility.

A Task consists of Business Logic, Presentation Logic, and a Plug-in Descriptor:

Business Logic

• Contained in Java files.
• Communicates with iManager through the Task class.
• Communicates with eDirectory using the AdminNamespace acquired from the AuthenticationBroker. Tasks can also make their own connection to any back end resource, and the Task is responsible for cleaning up any connections made. Current iManager credentials can also be obtained through the AuthenticationBroker to assist in single sign-on. The AuthenticationBroker can be obtained from the PluginContext object passed into the execute method using context.getAuthenticationBroker().
• Can put attributes on the HttpServletRequest for use by the Presentation Logic. Use context.getRequest() to obtain the HttpServletRequest.
• See the "Helper Classes" below for more class that can help you write your Task.

Presentation Logic

• Contained in JSP files in webapps/nps/portal/modules/(moduleid)/skins/default/devices/(device type).
• Can read attributes from the HttpServletRequest given by the Business Logic.
• Current valid device types are: "browser" meaning Internet Explorer, "mozilla" meaning Mozilla based browsers like Netscape, Mozilla, and Firefox, "default" meaning all other browsers, and "pocket" meaning pda devices like Palm, Windows CE, etc....
• Generally, if you are not doing device specific functionality like drag and drop or heavy use of browser specific JavaScript in your JSP files, you can put all of your JSP files in the "default" device directory. iManager looks on a file by file basis for a specific JSP file, meaning you can have 100 generic JSP files in the "default" directory, and two Internet Explorer specific JSP files in the "browser" directory. iManager will look first for a device specific JSP file and then in the "default" directory for a generic JSP.
• See the iMan Tag Library Reference and iMan Tag Library Demo on the "Developer" view of iManager for more information on helper tags you can use in your JSP files.

Plug-in Descriptor

• Contained in XML files in webapps/nps/portal/modules/(moduleid)/install or webapps/nps/portal/modules/(moduleid)/plugins. Tasks should generally be registered in the install directory. Plugins that do not appear as selectable Tasks down the left side should be registered in the plugins directory.
• Registers Modules, Roles, Tasks, PropertyBookPages, etc... with iManager.
• An XML plug-in descriptor can contain multiple Roles, Tasks, and PropertyBookPages in the same file (the file name does not matter).
• You should pick a unique id for your module (called the moduleid) as a short but unique name representing your product. For example, GroupWise could use GW as its moduleid. Use the moduleid to help guarantee uniqueness throughout iManager, such as in the file system under webapps/nps/portal/modules/(moduleid) directory where you store module specific files, in the ID of your tasks (ex. <id>moduleid.MyTask<id>), and when you get and put settings on the session cache using context.setAttribute( "moduleid.mysetting", "settingvalue" ).
• See the iManager XML Schema for Plug-ins under the task element for more information on constructing your plug-in descriptor.

All elements of a Task are zipped up in a module file with a .npm extension. See the iManager 2.x Developer Kit for more information on writing Tasks, the iManager file structure of where to put the different elements of the task, and how to build .npm files.

Do NOT hardcode the "nps" name in any paths to files in JSPs or referenced by your business logic. The web application name "nps" may change in the future, and you can use the TaskContext method context.getModulesPath() to return the path in your JSP file to the webapps/nps/portal/modules directory.

Helper classes

The TaskContext object (based upon PluginContext) given in the execute method allows you access to all information needed for your Task. See PluginContext for details as to the objects your task can access.

There are several static classes that may be of help to you in writing your task. See the eMFrameUtils and DirUtils classes for more information. Some of the DirUtils methods require an instantiated DirUtils object. You can obtain an instantiated DirUtils object from the PluginContext passed into the execute method using context.getDirUtils().

Debug logging is available through static methods on the D class. Debug output always shows up on STDERR, but can be configured to go to the STDOUT and to a file with various debugging levels.

Order of methods called on your Task:

• shouldRun(javax.servlet.http.HttpServletRequest, java.lang.String) - Before your class is instantiated, this method is called to see if iManager should instantiate your Task and display it for selection by the user. If you have special considerations to check before your task is shown (such as your Task will only work on a particular operating system, if you require schema extentions to be performed, etc...), overwrite the shouldRun call and do any checking. Make sure to call the parent shouldRun method as well.
• init(com.novell.emframe.dev.PluginContext, org.jdom.Document) - When your class is instantiated, this method is called to perform any initialization. Your task will only be instantiated when the user clicks to launch your task. Your task is NOT instantiated when the user logs in or when iManager starts up.
• execute(com.novell.emframe.dev.TaskContext, java.util.Properties) - This method is called repeatedly every time your Task is supposed to displayed it's content. Set your JSP file with the setUIPage(java.lang.String) call in your execute method. Make sure to call setUIPage() each time execute is called so the proper JSP file can be used. Some methods like eMFrameUtils.setMessage() and eMFrameUtils.setErrorMessage() will call the setUIPage call for you to set the JSP to be a generic message or error JSP. Also make sure your JSP file includes your taskId=(your task id) on the form or as a parameter on URLs you want to get back to your Task so that your execute method can retrieve the information.
• release() - This method is called when the user logs out or your Task's lifecycle is complete. Overwrite this method if you need to perform any cleanup before your task is released.

Lifecycle of a Task:

Generally, a Task's lifecycle begins when a user clicks on the link in the left menu launching the Task. Your task is actually being delegated the right frame from the "fw.HomePage" Task. If the user clicks on the link to launch your task again, iManager looks for a previous instance of the Task and releases it. iManager then instantiates a new instance so the Task can begin clean. When the user logs out, all Tasks are released. However, your Task may be released before logout if the user clicks to launch your Task again, or if your Task tells iManager that it is complete through the URL:
webacc?NPService=fw.LaunchService&NPAction=Return&return=(return type)&returnID=(your task id).

Some of the iManager Tag Library controls will return the above URL for you to signal to iManager that your task is complete. See the iManager 2.x Developer Kit documentation on Launching Tasks and Delegating Tasks for more information on Task lifecycle.

Also, you should not assume that the Task lifecycle corresponds to the HttpSession lifecycle. The HttpSession begins when the device (usually a browser) connects to the web servlet engine (ie. Tomcat). The HttpSession stays around until the browser is closed, meaning the user can login to a tree in iManager, run your Task, logout, login to another tree, run your Task again, and logout all with the same HttpSession. Therefore, your Task should NOT put anything directly on the HttpSession unless it also cleans up whatever it puts on the HttpSession when your Task is released. Instead, use the TaskContext passed into the execute method and call context.getAttribute(), context.setAttribute() context.removeAttribute() to get, put, and remove Objects in the session cache. iManager automatically cleans up the session cache when the user logs out of a tree.

Deprecated classes

Do not extend directly from com.novell.nps.gadgetManager.BaseGadgetInstance or use any com.novell.nps or com.novell.emframe.fw classes. Support for this has been deprecated. All tasks should extend the Task class and use calls in com.novell.emframe.dev. Do not write using XSL stylesheets as this has been deprecated as well. All tasks should use JSP files as their presentation logic.

See Also:

PluginContext, eMFrameUtils, DirUtils, D, Serialized Form

Field Summary

Fields inherited from class com.novell.nps.gadgetManager.BaseGadgetInstance

CONFIGURABLE, gadgetAssignment, gadgetAssignmentDN, gadgetCode, gadgetInstanceID, GETDATA, HANDLE_ACTION_ERROR_STATE, helpURL, m_doc, m_JSPDataObject, m_moduleStylesheet, m_previousState, myLocale, PROCESSREQUEST, repeatable, resBundle, session, state, STATE_SHOW_USER_CONFIG, STATE_USER_CONFIG_COMPLETE, windowState

Fields inherited from interface com.novell.nps.gadgetManager.GadgetInstance

FULLPAGE_BRANDING_AREA_MODE, FULLPAGE_DATA_MODE, FULLPAGE_REQUEST_PROPERTY, GADGET_DN, GADGET_INSTANCE_ARGS, GADGET_INSTANCE_CLASS, GADGET_INSTANCE_ID_PROPERTY, LAUNCH_TYPE_DELEGATE, LAUNCH_TYPE_LAUNCH, LIFECYCLE_TYPE_EXISTING, LIFECYCLE_TYPE_NEW, LIFECYCLE_TYPE_RECREATE, LIFECYCLE_TYPE_RESET, LIFECYCLE_TYPE_REUSE, PARAM_RETURN_STATUS, RETURN_STATUS_CANCEL, RETURN_STATUS_CANCEL_ABORT, RETURN_STATUS_CANCEL_CONTINUE, RETURN_STATUS_ERROR_ABORT, RETURN_STATUS_ERROR_CONTINUE, RETURN_STATUS_FINISHED, STATE_PROPERTY, TEXT_HTML, TEXT_XML, WINDOW_STATE_MAXIMIZED, WINDOW_STATE_MINIMIZED

Constructor Summary

Task()

Method Summary

static java.lang.String	buildQueryString(javax.servlet.http.HttpServletRequest req, boolean removeSearchParams) Static call to help with debugging by outputtin all parameters on the HttpServletRequest.
void	execute(javax.servlet.http.HttpServletRequest origReq) Deprecated. As of iManager 2.0, use execute(TaskContext context, Properties resultStrings)
void	execute(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) Deprecated. As of iManager 2.0, use execute(TaskContext context, Properties resultStrings)
abstract boolean	execute(TaskContext context, java.util.Properties resultStrings) Abstract class all Tasks must implement.
void	init(PluginContext context, org.jdom.Document doc) When your class is instantiated, this method is called to perform any initialization.
protected boolean	isInitialized() Returns whether the Task has been initialized.
static void	isPluginAvailable(PluginContext context, org.jdom.Document doc) Deprecated. As of iManager 2.0, use shouldRun() instead.
void	release() Overwrite this method if you need to perform cleanup when your task is released for garbage collection by iManager.
protected void	setInitialized(boolean initialized) Sets whether the Task has been initialized.
void	setUIPage(java.lang.String moduleStylesheet) Sets the JSP page to use for the current request.
static void	shouldRun(javax.servlet.http.HttpServletRequest req, java.lang.String sServiceName) Overwrite this method if the task needs to check conditions to determine if the task is able to be run.

Methods inherited from class com.novell.nps.gadgetManager.BaseGadgetInstance

addActionListener, callGetData, clearDocument, configureApply, configureCancel, configureComplete, createDocument, findURIForLocFile, getAction, getActionIcons, getAllowProcessRequestAsync, getConfig, getConfigObjectSetting, getConfigObjectSettings, getConfigSetting, getConfigSetting, getConfigSettings, getConfigSettingValue, getConfigSettingValues, getConfiguredUniqueID, getContainedGadgetInstanceStylesheets, getCustomizeQueryString, getData, getDataFromLastTry, getDocument, getFullPageMode, getGadgetAssignment, getGadgetAssignmentDN, getGadgetInstanceID, getGadgetXMLEndTag, getGadgetXMLStartTag, getHandleActionErrorStateData, getIntConfigSetting, getJSPDataObject, getJSPPage, getLangResourceURI, getLaunchType, getLifeCycleType, getLocale, getLocHelpURL, getLocResourceURI, getManagementServiceSet, getOriginalServiceName, getParam, getParentInstance, getPortalConnection, getPreferredDataType, getPreferredName, getPreferredName, getPrimary, getProxyServer, getRedirectionOrSelf, getRepeatParams, getResourceBundle, getResourcePathBase, getReturnStatus, getRootDelegator, getRootNodeName, getSession, getState, getStylesheetAndResourceSets, getStyleSheetName, getUserConfigCompleteData, getWindowState, handleAction, handlePostRequestActions, hasHelp, init, isConfigSettingCumulative, isConfigSettingOverwriteable, isForceRead, isTimedOut, onPageMaximize, onPageMinimize, onPortalInit, onShowUserConfigAction, onUserConfigCompleteAction, outputHTMLError, parseMultipartFormData, prepare, processRequest, processRequest, processSecondaryGadgetResults, removeActionListener, reset, returnToPrimary, setAllowProcessRequestAsync, setConfigSetting, setConfigSetting, setForceRead, setGadgetAssignment, setGadgetAssignmentDN, setGadgetInstanceID, setGetDataFromLastTry, setLaunchType, setLifeCycleType, setLocale, setModuleStylesheet, setParentInstance, setPrimary, setRedirectionOrSelf, setRepeatParams, setRequestedDataType, setResourceBundle, setRootDelegator, setSession, setState, setTimedOut, setWindowState, supportsDeviceCharacteristics, writeConfig, writeGadgetXMLEndTag, writeGadgetXMLStartTag

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Task

public Task()

Method Detail

buildQueryString

public static java.lang.String buildQueryString(javax.servlet.http.HttpServletRequest req,
                                                boolean removeSearchParams)

Static call to help with debugging by outputtin all parameters on the HttpServletRequest. You can use this call as part of D.log(Task.buildQueryString(req, false)); to output all parameters on the request to see if the necessary parameters have been added for your Task.

Parameters:

req - The current HttpServletRequest

removeSearchParams - boolean: true if the Object Selector's search parameters should be removed from the output String, false to return all parameters on the output String

Returns:

String containing all of the parameters on the HttpServletRequest

See Also:

D

execute

public void execute(javax.servlet.http.HttpServletRequest origReq)

Deprecated. As of iManager 2.0, use execute(TaskContext context, Properties resultStrings)

Called when the task is expected to return results to the browser. This call is deprecated and is only around for backwards compatibility. Tasks should not overwrite this method, but should instead implement the execute(TaskContext context, Properties resultStrings) method.

Parameters:

origReq - HttpServletRequest object

See Also:

execute(com.novell.emframe.dev.TaskContext, java.util.Properties)

execute

public void execute(javax.servlet.http.HttpServletRequest req,
                    javax.servlet.http.HttpServletResponse resp)

Deprecated. As of iManager 2.0, use execute(TaskContext context, Properties resultStrings)

Called when the task is expected to return results to the browser. This call is deprecated and is only around for backwards compatibility. Tasks should not overwrite this method, but should instead implement the execute(TaskContext context, Properties resultStrings) method.

Parameters:

req - HttpServletRequest object

resp - HttpServletResponse object

See Also:

execute(com.novell.emframe.dev.TaskContext, java.util.Properties)

execute

public abstract boolean execute(TaskContext context,
                                java.util.Properties resultStrings)

Abstract class all Tasks must implement. This method is called repeatedly every time your Task is supposed to displayed it's context to the browser or other device. The init will be called prior to the first execute call to allow your task to initialize.

Make sure to call setUIPage() each time execute is called so the proper JSP file can be used. You can add key/value items directly to the HttpServletRequest for use by the JSP file using the context.getRequest().setAttribute() method.

If you encounter an error during execution or want to display a generic success message after successful completion of your Task, there are several static classes you can call that will call your Task's setUIPage method and use a generic JSP that handles errors and success messages. See the eMFrameUtils.setMessage and eMFrameUtils.setErrorMessage methods for more information.

Also make sure your JSP file includes your taskId=(your task id) on the form or as a parameter on URLs if you want to get back to your Task so that your execute method can retrieve the information.

Example form:
<FORM name="EditFlagsForm" method="post" action="webacc">
<input type="hidden" name="taskId" value="<%= c.var("taskId") %>">

Parameters:

context - TaskContext of the Task allows you access to all information needed for your Task. See PluginContext for details as to the objects your task can access.

resultStrings - Properties object with key/value pairs that will automatically be added to the HttpServletRequest by iManager. However, the recommended way is to add items directly to the HttpServletRequest using the context.getRequest().setAttribute() method. This resultStrings properties object is kept here for backwards compatibility.

Returns:

boolean: true if execution was successful, false if there was an error and a generic error JSP needs to be displayed

See Also:

init(com.novell.emframe.dev.PluginContext, org.jdom.Document), setUIPage(java.lang.String), PluginContext, eMFrameUtils

init

public void init(PluginContext context,
                 org.jdom.Document doc)

When your class is instantiated, this method is called to perform any initialization. Your task is NOT instantiated when the user logs in or when iManager starts up. Your task will only be instantiated when the user clicks to launch your task.

Parameters:

context - PluginContext of the Task allows you access to all information needed for your Task. See PluginContext for details as to the objects your task can access.

doc - XML Document registering the Task with iManager

isInitialized

protected boolean isInitialized()

Returns whether the Task has been initialized.

Returns:

boolean: true if the Task has been initialized, false if otherwise.

isPluginAvailable

public static void isPluginAvailable(PluginContext context,
                                     org.jdom.Document doc)
                              throws PluginException

Deprecated. As of iManager 2.0, use shouldRun() instead.

This function is called to see if the task should be run based upon conditions known to the task. For instance, by default the function calls supportsDeviceCharacteristics(). Other conditions could be an unsupported server operating system, current user logged into the tree, etc.... However, this call is deprecated and Tasks should implement shouldRun instead.

Parameters:

context - PluginContext of the Task allows you access to all information needed for your Task. See PluginContext for details as to the objects your task can access.

doc - XML Document used to register your task with iManager

Throws:

PluginException - containing a message as to why the task is not able to run

See Also:

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

release

public void release()

Overwrite this method if you need to perform cleanup when your task is released for garbage collection by iManager. Any connections initialized directly by this Task should be cleaned up. Make sure to call the parent release() method so the system can do any cleanup it needs.

setInitialized

protected void setInitialized(boolean initialized)

Sets whether the Task has been initialized.

Parameters:

initialized - boolean: true if the Task has been initialized, false if otherwise.

setUIPage

public void setUIPage(java.lang.String moduleStylesheet)

Sets the JSP page to use for the current request. The format of the string should be "moduleid/stylesheetname" (ex. "base/myTask.jsp"). iManager will then search under webapps/nps/portal/moduleid/skins/default/devices for a matching JSP file based upon the current client device.

Parameters:

moduleStylesheet - String containing the JSP file to use for the current request

shouldRun

public static void shouldRun(javax.servlet.http.HttpServletRequest req,
                             java.lang.String sServiceName)
                      throws java.lang.Exception

Overwrite this method if the task needs to check conditions to determine if the task is able to be run. For instance, by default the function calls supportsDeviceCharacteristics(). Other conditions could be an unsupported server operating system, current user logged into the tree, etc....

If the task overwrites this method, it should always call the Task.shouldRun() first so the system can do its checks.

Simply return if the task should be able to run. Otherwise, throw an exception with a descriptive string describing why the task cannot run.

Parameters:

req - The current HttpServletRequest

sServiceName - The service name the task will have if it is instantiated

Throws:

java.lang.Exception - if the task should not run