001: package org.enhydra.shark.api.client.wfservice;
002:
003: import org.enhydra.shark.api.client.wfmc.wapi.WMConnectInfo;
004: import org.enhydra.shark.api.client.wfmc.wapi.WMSessionHandle;
005: import org.enhydra.shark.api.client.wfmodel.WfActivity;
006: import org.enhydra.shark.api.client.wfmodel.WfActivityIterator;
007: import org.enhydra.shark.api.client.wfmodel.WfAssignment;
008: import org.enhydra.shark.api.client.wfmodel.WfAssignmentIterator;
009: import org.enhydra.shark.api.client.wfmodel.WfProcess;
010: import org.enhydra.shark.api.client.wfmodel.WfProcessIterator;
011: import org.enhydra.shark.api.client.wfmodel.WfProcessMgr;
012: import org.enhydra.shark.api.client.wfmodel.WfResource;
013:
014: /**
015: * Interface used to perform some administrative operations that concern execution engine
016: * objects.
017: * <p>
018: * The first method to be called by client application is the first method of this
019: * interface - connect(), and only if user authentication is OK, other methods can be used
020: * (otherwise, every method throws NotConnected exception).
021: *
022: * @author Sasa Bojanic
023: * @author Vladimir Puskas
024: */
025: public interface SharkConnection {
026:
027: /**
028: * This is the first method to be called in order to communicate with the engine. If
029: * the login parameters are correct, user can use other methods of this interface to
030: * communicate with the shark engine, and if not, he can't do anything.
031: *
032: * @param connectInfo structure holding connection request data
033: * @throws Exception If something unexpected happens.
034: */
035: void connect(WMConnectInfo connectInfo) throws Exception;
036:
037: void attachToHandle(WMSessionHandle shandle) throws Exception;
038:
039: /**
040: * Disconnects from shark engine.
041: *
042: * @throws Exception If something unexpected happens.
043: */
044: void disconnect() throws Exception;
045:
046: WMSessionHandle getSessionHandle() throws Exception;
047:
048: /**
049: * Returns WfResource object belonging to the user that has been connected to shark
050: * through this interface. This will be the WfResource object that has the same
051: * username attribute as the one used in connect() method. After getting this object,
052: * client application can present user a list of its assignments that can be retrieved
053: * throug this WfResource object.
054: *
055: * @return WfResource object belonging to the user.
056: * @throws Exception If something unexpected happens.
057: */
058: WfResource getResourceObject() throws Exception;
059:
060: /**
061: * Returns an iterator that can be used to retrieve WfProcessMgr objects that represent
062: * appropriate XPDL process definitions, and are used to create new process instances.
063: *
064: * @return WfProcessMgrIterator for retrieving WfProcessMgr objects.
065: * @throws Exception If something unexpected happens.
066: */
067: WfProcessMgrIterator get_iterator_processmgr() throws Exception;
068:
069: /**
070: * Returns an array of WfProcessMgr objects.
071: *
072: * @param max_number The maximum number of WfProcessMgr instances to be returned. If
073: * set to 0, all existing instances will be returned (this will be equal to
074: * the number of XPDL process definitions in all packages that are loaded
075: * into engine).
076: * @return Array of specified WfProcessMgr objects.
077: * @throws Exception If something unexpected happens.
078: */
079: WfProcessMgr[] get_sequence_processmgr(int max_number)
080: throws Exception;
081:
082: /**
083: * Returns an iterator that can be used to retrieve WfResource objects that represent
084: * appropriate shark users.
085: *
086: * @return WfResourceIterator for retrieving WfResource objects. that represent
087: * appropriate shark users.
088: * @throws Exception If something unexpected happens.
089: */
090: WfResourceIterator get_iterator_resource() throws Exception;
091:
092: /**
093: * Returns an array of WfResource objects.
094: *
095: * @param max_number The maximum number of WfResource instances to be returned. If set
096: * to 0, all existing instances will be returned.
097: * @return Specified array of WfResource objects.
098: * @throws Exception If something unexpected happens.
099: */
100: WfResource[] get_sequence_resource(int max_number) throws Exception;
101:
102: /**
103: * Returns WfProcessMgr object that has the given name, or null if such does not exist.
104: *
105: * @param name WfProcessMgr object name.
106: * @return WfProcessMgr with the given name, or null if does not exist.
107: * @throws Exception If something unexpected happens.
108: */
109: WfProcessMgr getProcessMgr(String name) throws Exception;
110:
111: /**
112: * Returns WfResource object that has the given username, or null if such doesn't
113: * exist.
114: *
115: * @param username username of WfResource instance.
116: * @return WfResource with the given name, or null if does not exist.
117: * @throws Exception If something unexpected happens.
118: */
119: WfResource getResource(String username) throws Exception;
120:
121: /**
122: * Returns WfProcess object that has the given Id, or null if such does not exist.
123: *
124: * @param procId process instance Id.
125: * @return WfProcess with the given name, or null if does not exist.
126: * @throws Exception If something unexpected happens.
127: */
128: WfProcess getProcess(String procId) throws Exception;
129:
130: /**
131: * Returns WfActivity object that has the given Id, or null if such doesn't exist.
132: *
133: * @param procId activity's process Id.
134: * @param actId activity instance Id.
135: * @return WfActivity with the given Id, or null if does not exist.
136: * @throws Exception If something unexpected happens.
137: */
138: WfActivity getActivity(String procId, String actId)
139: throws Exception;
140:
141: /**
142: * Returns WfAssignment object for activity with given Id, and resource with the given
143: * username, or null if such doesn't exist.
144: *
145: * @param procId the assignment's activity's process instance Id.
146: * @param actId the assignment's activity instance Id.
147: * @param username the assignement's username
148: * @return Specified WfAssignment , or null if does not exist.
149: * @throws Exception If something unexpected happens.
150: */
151: WfAssignment getAssignment(String procId, String actId,
152: String username) throws Exception;
153:
154: /**
155: * Returns WfAssignment object for given Id, or null if such doesn't exist. NOTE: this
156: * method is here only because of standardization (having one method with transaction,
157: * and other without), and is not supposed to be used in normal situations - tool
158: * agents can call the same method but with additional transaction parameter, and user
159: * applications should call the same method but with actId and username parameters
160: * instead of assId parameter.
161: *
162: * @param procId the assignment's activity's process instance Id.
163: * @param assId the assignment Id.
164: * @return Specified WfAssignment , or null if does not exist.
165: * @throws Exception If something unexpected happens.
166: */
167: WfAssignment getAssignment(String procId, String assId)
168: throws Exception;
169:
170: /**
171: * @return unbound assignment iterator
172: * @throws Exception
173: */
174: WfAssignmentIterator get_iterator_assignment() throws Exception;
175:
176: /**
177: * @return unbound process iterator
178: * @throws Exception
179: */
180: WfProcessIterator get_iterator_process() throws Exception;
181:
182: /**
183: * @return unbound activity iterator
184: * @throws Exception
185: */
186: WfActivityIterator get_iterator_activity() throws Exception;
187:
188: }
|