# Task Control Interface

The Task control enables a business process to create a single Task instance, manage its state and data, and provide callback methods that report status. Each Task control operates on a single active Task instance. You can extend this control.

The following are the Task control methods:

    package com.bea.control;

    import weblogic.jws.control.Control;
    import com.bea.control.Extensible;
    import com.bea.wli.worklist.api.TaskInfo;
    import com.bea.wli.worklist.xml.TaskCreationXMLDocument;
    import com.bea.wli.worklist.xml.TaskInfoXMLDocument;
    import com.bea.wli.worklist.xml.TaskUpdateXMLDocument;

    /**
     * Task control interface.
     */

    public interface TaskControl extends Control {

        /**
         * the control jc tag.
         */

        static final String TAG_TASK = "jc:task";

        /**
         * the control advanced options jc tag.
         */

        static final String TAG_ADVANCED = "jc:advanced";

        /**
    		     * the control assignement jc tag.
         */

        static final String TAG_ASSIGNEE = "jc:assignee";

        /**
         * Set the TaskId the control is linked to. The taskId can only be set once.
         * When a task is created, its taskId is set to the control if no taskId
         * has been set before or return an exception otherwise.
         * If you want to work with more than one taskId you can use multiple
         * TasksControls, a TaskControl factory or the WorklistControl.

         */

        public void setTaskId(String taskId);

        public String getTaskId();

        /**
         * Create and optionally assigns a new task using an XML interface
         * @param doc the task parameters
         * @return the taskId
         */

        public String createTask(TaskCreationXMLDocument doc);

        /**
         * The @jc:task-create tag is used to annotate a JBCX method that
         * creates a new task. This method can at most be called once by control
         *and returns the taskId.

         * The callbacks are registered to the new task created

         */

        static final String TAG_TASK_CREATE                 = "jc:task-create";

        static final String ATTR_CREATE_NAME                = "name";

        static final String ATTR_CREATE_DESCRIPTION         = "description"; // optional

        static final String ATTR_CREATE_COMMENT             = "comment"; //optional

        static final String ATTR_CREATE_PRIORITY            = "priority"; // optional

        static final String ATTR_CREATE_CLAIM_DUE_DATE      = "claim-due-date"; // optional

        static final String ATTR_CREATE_COMPLETION_DUE_DATE   = "completion-due-date";
    // optional, if no expiration date is specified the task will never expire.

        static final String ATTR_CREATE_CLAIM_DUE_BUSINESS_DATE = "claim-due-business-date"; //optional

        static final String ATTR_CREATE_CLAIM_USER_CALENDAR = "claim-user-calendar"; //optional

        static final String ATTR_CREATE_CLAIM_CALENDAR      = "claim-calendar"; //optional

        static final String ATTR_CREATE_COMPLETION_DUE_BUSINESS_DATE =
    "completion-due-business-date"; //optional

        static final String ATTR_CREATE_COMPLETION_USER_CALENDAR = "completion-user-calendar"; //optional

        static final String ATTR_CREATE_COMPLETION_CALENDAR = "completion-calendar"; //optional

        static final String ATTR_CREATE_OWNER               = "owner";

        static final String ATTR_CREATE_CAN_BE_REASSIGNED   = "can-be-reassigned";
    // optional: by default true

        static final String ATTR_CREATE_CAN_BE_RETURNED     = "can-be-returned";
    // optional by default false

        static final String ATTR_CREATE_CAN_BE_ABORTED      = "can-be-aborted";
    // optional by default true

        static final String ATTR_CREATE_REQUEST             = "request";
    // optional, can be mapped to any serializable object.

        static final String ATTR_CREATE_REQUEST_MIME_TYPE   = "request-mime-type";
    //optional

        /**
         * The @jc:task-assign tag is used to annotate a JBCX method that
         * assign or reassign a task. The algorithm name is used to determine the way
         * a task is assigned. If no name is pecified the default algorithm is used
         * and the args must be of type String[];
         * In any case the attribute "args" is required and must be of type Object[].
         *
         */

        static final String TAG_TASK_ASSIGN          = "jc:task-assign";

        static final String ATTR_ASSIGN_USER         = "user";

        static final String ATTR_ASSIGN_GROUP        = "group";

        static final String ATTR_ASSIGN_ALGORITHM    = "algorithm";

        static final String TAG_TASK_RESUME          = "jc:task-resume";

        static final String TAG_TASK_SUSPEND         = "jc:task-suspend";

        public static final String TAG_TASK_ABORT    = "jc:task-abort";

        public TaskInfo getTaskInfo();

        public TaskInfoXMLDocument getTaskInfoXMLDocument();

        public String[] getTaskPropertiesNames();

        /**
         *  The return type of the method JBCX is used to determine
         *  what is returned.
         */

        public static final String TAG_TASK_GET_REQUEST     = "jc:task-get-request";

        //**
         *  The return type of the method JBCX is used to determine
         *  what is returned.
         */

        public static final String TAG_TASK_GET_RESPONSE    = "jc:task-get-response";

        //**
         *  The return type of the method JBCX is used to determine
         *  what is returned.
         */

        public static final String TAG_TASK_GET_PROPERTY    = "jc:task-get-property";

        public static final String ATTR_GET_PROPERTY_NAME   = "name";

        public static final String TAG_TASK_SET_PROPERTY    = "jc:task-set-property";

        public static final String ATTR_SET_PROPERTY_NAME   = "name";

        public static final String ATTR_SET_PROPERTY_VALUE  = "value";

        public static final String ATTR_SET_PROPERTY_MAP    = "map";

        public static final String TAG_TASK_REMOVE_PROPERTY = "jc:task-remove-property";

        public static final String ATTR_REMOVE_PROPERTY_NAME= "name";

        /**
         * The @jc:task-update tag is used to annotate a JBCX method that
         * update the task properties. You can modify one or more properties at the same time.
         */

        static final String TAG_TASK_UPDATE                 = "jc:task-update";

        static final String ATTR_UPDATE_CAN_BE_ABORTED         = "can-be-aborted"; // optional

        static final String ATTR_UPDATE_CAN_BE_REASSIGNED      = "can-be-reassigned"; // optional

        static final String ATTR_UPDATE_CAN_BE_RETURNED        = "can-be-returned"; // optional

        static final String ATTR_UPDATE_COMMENT             = "comment"; //optional

        static final String ATTR_UPDATE_PRIORITY            = "priority"; // optional

        static final String ATTR_UPDATE_CLAIM_DUE_DATE      = "claim-due-date"; //optional

        static final String ATTR_UPDATE_COMPLETION_DUE_DATE   = "completion-due-date"; //optional

        static final String ATTR_UPDATE_CLAIM_DUE_BUSINESS_DATE =
    "claim-due-business-date"; //optional

        static final String ATTR_UPDATE_CLAIM_USER_CALENDAR = "claim-user-calendar"; //optional

        static final String ATTR_UPDATE_CLAIM_CALENDAR      = "claim-calendar"; //optional

        static final String ATTR_UPDATE_COMPLETION_DUE_BUSINESS_DATE =
    "completion-due-business-date"; //optional

        static final String ATTR_UPDATE_COMPLETION_USER_CALENDAR =
    "completion-user-calendar"; //optional

        static final String ATTR_UPDATE_COMPLETION_CALENDAR = "completion-calendar"; //optional

        static final String ATTR_UPDATE_OWNER               = "owner"; //optional

        static final String ATTR_UPDATE_REQUEST             = "request"; //optional

        static final String ATTR_UPDATE_REQUEST_MIME_TYPE   = "request-mime-type"; //optional

        static final String ATTR_UPDATE_RESPONSE               = "response"; //optional

        static final String ATTR_UPDATE_RESPONSE_MIME_TYPE     = "response-mime-type"; //optional

        public void updateTask(TaskUpdateXMLDocument doc);

        static final Integer CALENDAR_TYPE_SYSTEM = new Integer(0);

        static final Integer CALENDAR_TYPE_USER_OR_GROUP = new Integer(1);

        static final Integer CALENDAR_TYPE_NAME = new Integer(2);

        public interface Callback

        {

        /**
         * Internal callback method used to implement user-defined callbacks. When a
         * task is set to the control instance, all the callback are registered to
         * the task.
         *
         */

        static final String TAG_TASK_EVENT               = "jc:task-event";

        // event-types are: "completed, aborted, claimed, suspended, resumed,
        // assigned, task-expired, task-claim-expired"

        static final String ATTR_TASK_EVENT_TYPE         = "event-type";
        static final String ATTR_TASK_EVENT_TIME         = "time";//optional

        // optional, if a user has performed an action changing the state
        static final String ATTR_TASK_EVENT_USER        = "user"; // optional

        // task response passed along "completed" with the event
        static final String ATTR_TASK_EVENT_RESPONSE        = "response"; // optional

        }
    }

### Sample Extended Task Control

The following code shows an example of an extended control. This code is automatically created by the control wizard.

    package processes;

    import weblogic.jws.*;
    import com.bea.control.TaskControl;
    import com.bea.xml.XmlObject;
    import java.util.Date;

    /**
     * @jc:task
     */

    public interface task1 extends TaskControl, com.bea.control.ControlExtension
    {
        /**
        * @jc:task-create
        *   name="{name}"
        */

        public String createTaskByName(String name);

        /**
         * @jc:task-assign
         * user="{users}"
         * group="{groups}"
         * algorithm="ToUsersAndGroups"
         */

        public void assignTaskToUsersAndGroups(String[] users, String[] groups);

        /**
         * @jc:task-assign
         * user="{user}"
         * algorithm="ToUser"
         */

        public void assignTaskToUser(String user);

        /**
         * @jc:task-assign
         * group="{group}"
         * algorithm="ToUserInGroup"
         */

        public void assignTaskToUserInGroup(String group);

        /**
         * @jc:task-update
         * request={xml}
         */

        public void setRequest(XmlObject xml);

        /**
         * @jc:task-update
         * response={xml}
         */

        public void setResponse(XmlObject xml);

        /**
         * @jc:task-update
         * comment={comment}
         */

        public void setComment(String comment);

        /**
         * @jc:task-update
         * priority={priority}
         */

        public void setPriority(Integer priority);

        /**
         * @jc:task-update
         * owner={owner}
         */

        public void setOwner(String owner);

        /**
         * @jc:task-update can-be-aborted="{aborted}" can-be-returned="{returned}"
         *can-be-reassigned="{reassigned}"
         */

        public void setPermissions(Boolean aborted, Boolean returned, Boolean reassigned);

        /**
         * @jc:task-update completion-due-date="{date}"
         *
         */

        public void setCompletionDueDate(Date date);

        /**
         * @jc:task-update completion-due-business-date={duration}
         * completion-calendar={calendarID}
         */

        public void setCompletionDueBusinessDate(String duration, String calendarID);

        /**
         * @jc:task-update claim-due-business-date={duration}
         * claim-calendar={calendarID}
         */

        public void setClaimDueBusinessDate(String duration, String calendarID);

       /**
         * @jc:task-update claim-due-business-date={duration}
         */

        public void setClaimDueBusinessDateSystemCalendar(String duration);

        /**
         * @jc:task-update completion-due-business-date={duration}
         */

        public void setCompletionDueBusinessDateSystemCalendar(String duration);

        /**
         * @jc:task-update claim-due-date="{date}"
         */

        public void setClaimDueDate(Date date);

        /**
         * @jc:task-abort enabled="true"
         */

        public void abortTask();

        /**
         * @jc:task-resume enabled="true"
         */

        public void resumeTask();

        /**
         * @jc:task-suspend enabled="true"
         */

        public void suspendTask();

        /**
         * @jc:task-get-request enabled="true"
         */

        public XmlObject getRequest();

        /**
         * @jc:task-get-response enabled="true"
         */

        public XmlObject getResponse();

        /**
         * @jc:task-get-property name="{name}"
         */

        public String getProperty(String name);

        /**
         * @jc:task-set-property name="{name}" value="{value}"
         */

        public void setProperty(String name, String value);

        /**
         * @jc:task-remove-property name="{name}"
         */

        public void removeProperty(String name);

        public interface Callback extends TaskControl.Callback {

           /**
            * @jc:task-event event-type="complete" response="{response}"
            */

            void onTaskCompleted(XmlObject response);

            /**
            * @jc:task-event event-type="abort" response="{response}"
            */

            void onTaskAborted(XmlObject response);

            /**
            * @jc:task-event event-type="expire" time="{time}"
            */

            void onTaskOverdue(Date time);

        }
    }