001: /*
002: * This file is part of the WfMOpen project.
003: * Copyright (C) 2001-2003 Danet GmbH (www.danet.de), GS-AN.
004: * All rights reserved.
005: *
006: * This program is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU General Public License as published by
008: * the Free Software Foundation; either version 2 of the License, or
009: * (at your option) any later version.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: *
020: * $Id: ResourceAssignmentService.java,v 1.5 2007/02/27 14:34:20 drmlipp Exp $
021: *
022: * $Log: ResourceAssignmentService.java,v $
023: * Revision 1.5 2007/02/27 14:34:20 drmlipp
024: * Some refactoring to reduce cyclic dependencies.
025: *
026: * Revision 1.4 2006/09/29 12:32:07 drmlipp
027: * Consistently using WfMOpen as projct name now.
028: *
029: * Revision 1.3 2005/10/15 21:19:38 mlipp
030: * Added support for providing WfAssignment
031: * implementations based purely on methods of Activity.
032: *
033: * Revision 1.2 2004/12/27 12:54:13 mlipp
034: * Fixed comment.
035: *
036: * Revision 1.1.1.2 2004/08/18 15:17:38 drmlipp
037: * Update to 1.2
038: *
039: * Revision 1.4 2004/06/14 19:37:20 lipp
040: * Fixed assignment functions and cleaned up assignment related
041: * interfaces.
042: *
043: * Revision 1.3 2003/06/27 08:51:44 lipp
044: * Fixed copyright/license information.
045: *
046: * Revision 1.2 2003/04/25 14:50:58 lipp
047: * Fixed javadoc errors and warnings.
048: *
049: * Revision 1.1 2002/12/19 21:37:42 lipp
050: * Reorganized interfaces.
051: *
052: * Revision 1.19 2002/11/26 11:23:29 lipp
053: * Modified RemoteException comment.
054: *
055: * Revision 1.18 2002/05/17 13:59:58 lipp
056: * Removed no longer needed import.
057: *
058: * Revision 1.17 2002/01/23 15:27:57 huaiyang
059: * Replace the type of resSel in autoAssignResources from Object to Participant.
060: *
061: * Revision 1.16 2002/01/15 13:42:21 lipp
062: * Added resourceByKey to ResourceAssignmentService and some missing
063: * NoSuchResourceExceptions in various methods.
064: *
065: * Revision 1.15 2002/01/15 11:25:59 huaiyang
066: * Add the assigned activity function to the mgmt client.
067: *
068: * Revision 1.14 2002/01/09 14:48:51 lipp
069: * Changed access to current user as resource.
070: *
071: * Revision 1.13 2002/01/09 14:00:01 lipp
072: * Cleaned up relation between wfcore, resource assignment and resource
073: * management service.
074: *
075: * Revision 1.12 2001/12/20 22:32:06 lipp
076: * Removed no longer needed method.
077: *
078: * Revision 1.11 2001/12/20 22:22:50 lipp
079: * Resource release implemented.
080: *
081: * Revision 1.10 2001/12/20 16:23:06 lipp
082: * Fixed typo.
083: *
084: * Revision 1.9 2001/12/19 22:07:29 lipp
085: * Automatic resource assignment (workflow core part) implemented.
086: *
087: * Revision 1.8 2001/12/18 22:16:53 lipp
088: * Restructured DOM generation, implemented "assignments" method from ras.
089: *
090: * Revision 1.7 2001/12/17 09:15:50 lipp
091: * Javadoc fixes.
092: *
093: * Revision 1.6 2001/12/16 21:48:57 lipp
094: * addAssignment implemented.
095: *
096: * Revision 1.5 2001/12/13 16:26:05 lipp
097: * Added method and improved comment.
098: *
099: * Revision 1.4 2001/12/11 12:47:37 lipp
100: * JavaDoc fixes.
101: *
102: * Revision 1.3 2001/11/30 15:39:37 lipp
103: * Evolving resource assignment.
104: *
105: * Revision 1.2 2001/11/30 11:43:26 lipp
106: * javadoc fixes.
107: *
108: * Revision 1.1 2001/11/27 18:26:42 lipp
109: * Resource handling redesigned.
110: *
111: */
112: package de.danet.an.workflow.spis.ras;
113:
114: import java.util.Collection;
115:
116: import java.rmi.RemoteException;
117: import java.security.Principal;
118:
119: import de.danet.an.workflow.omgcore.InvalidResourceException;
120: import de.danet.an.workflow.omgcore.NotAssignedException;
121: import de.danet.an.workflow.omgcore.WfActivity;
122: import de.danet.an.workflow.omgcore.WfAssignment;
123: import de.danet.an.workflow.omgcore.WfResource;
124:
125: import de.danet.an.workflow.api.AlreadyAssignedException;
126: import de.danet.an.workflow.api.InvalidKeyException;
127: import de.danet.an.workflow.api.NoSuchResourceException;
128: import de.danet.an.workflow.api.Participant;
129:
130: /**
131: * This interface defines the resource assignment facility used by the
132: * workflow component. A central design issue for this interface is
133: * the identification of activites.<P>
134: *
135: * The {@link de.danet.an.workflow.omgcore.WfActivity#key
136: * "<code>key</code>" method} of <code>WfActivity</code> is by
137: * definition only unique within the scope of the containing process
138: * and can thus not easily be used to identify a single activity in a
139: * workflow engine. Even worse, a resource assignment service might
140: * be used by more than one workflow engine.<P>
141: *
142: * At this interface, an activity is therefore identified using an
143: * <code>ActivityFinder</code> and an identifier that is unique with
144: * respect to the <code>ActivityFinder</code>. The
145: * <code>ActivityFinder</code> provides both a namespace to allow
146: * different consumers to request resources and a means for the
147: * assignment facility to map the identifier back to an actual
148: * <code>WfActivity</code> object. See the description of {@link
149: * ActivityFinder <code>ActivityFinder</code>} for more details.<P>
150: *
151: * From the workflow engine's point of view, the resource assignment
152: * service is the only source of objects of type
153: * <code>WfResource</code> and <code>WfAssignment</code>.
154: *
155: * Implementations of resource assignment services may be (but need
156: * not be) based on a resource management service as defined in
157: * package {@link de.danet.an.workflow.spis.rms
158: * <code>de.danet.an.workflow.spis.rms</code>}.
159: */
160: public interface ResourceAssignmentService {
161:
162: /**
163: * Given a {@link java.security.Principal principal}, return the
164: * workflow resource associated with this principal.<P>
165: *
166: * As the workflow core does not have a defined access to a
167: * resource management facility, this mapping functionality must
168: * be brought to the workflow core by the resource assignment
169: * service. If the resource assignment service is based on a
170: * resource management service as defined in package {@link
171: * de.danet.an.workflow.spis.rms
172: * <code>de.danet.an.workflow.spis.rms</code>}, it can simply
173: * delegate this call to {@link
174: * de.danet.an.workflow.spis.rms.ResourceManagementService#asResource
175: * <code>ResourceManagementService.asResource</code>}.
176: *
177: * The workflow engine does not need this method for its
178: * operation; however, it provides a method for accessing this
179: * information as part of the client interface to ease the
180: * implementation of clients that e.g. want to generate a list of
181: * assignments for the current user. The implementation of this
182: * method by a resource assignment service is therefore
183: * optional. If not implemented, a call to this method must result
184: * in a {@link java.lang.UnsupportedOperationException
185: * <code>UnsupportedOperationException</code>}.<P>
186: *
187: * @param principal the principal.
188: * @return a <code>WfResource</code> object corresponding to the
189: * given principal.
190: * @throws InvalidKeyException if the resource with the given key
191: * can't be found.
192: * @throws RemoteException if a system-level error occurs.
193: * @since 1.2
194: */
195: WfResource asResource(Principal principal) throws RemoteException,
196: InvalidKeyException;
197:
198: /**
199: * Given the <code>key</code> of a <code>WfResource</code>
200: * (obtained with {@link WfResource#resourceKey
201: * <code>resourceKey()</code>}), return the workflow resource
202: * associated with this key.<P>
203: *
204: * For the workflow core, the resource assignment interface is the
205: * only source of <code>WfResource</code> objects. While {@link
206: * WfResource#resourceKey <code>resourceKey()</code>} provides an
207: * easy mapping of those objects to unique keys, the reverse
208: * mapping can only be provided by the resource management
209: * facility that has created the <code>WfResource</code>
210: * objects.<P>
211: *
212: * As the workflow core does not have a defined access to a
213: * resource management facility, this reverse mapping
214: * functionality must be brought to the workflow core by the
215: * resource assignment service. (Which is quite reasonable, as it
216: * has delivered the <code>WfResource</code> objects in the first
217: * place.) If the resource assignment service is based on a
218: * resource management service as defined in package {@link
219: * de.danet.an.workflow.spis.rms
220: * <code>de.danet.an.workflow.spis.rms</code>}, it can simply
221: * delegate this call to {@link
222: * de.danet.an.workflow.spis.rms.ResourceManagementService#resourceByKey
223: * <code>ResourceManagementService.resourceByKey</code>}.
224: *
225: * The workflow engine does not need this method for its
226: * operation; however, it provides a method for accessing this
227: * information as part of the client interface to ease the
228: * implementation of clients. The implementation of this method by
229: * a resource assignment service is therefore optional. If not
230: * implemented, a call to this method must result in a {@link
231: * java.lang.UnsupportedOperationException
232: * <code>UnsupportedOperationException</code>}.<P>
233: *
234: * @param key the key.
235: * @return a <code>WfResource</code> object corresponding to the
236: * given key.
237: * @throws InvalidKeyException if the resource with the given
238: * key can't be found. As the environment is a concurrent multi
239: * user environment, <code>WfResource</code> objects (and keys obtained
240: * from <code>WfResource</code> objects) may become invalid.
241: * @throws RemoteException if a system-level error occurs.
242: * @since 1.2
243: */
244: WfResource resourceByKey(String key) throws InvalidKeyException,
245: RemoteException;
246:
247: /**
248: * Returns at least the collection of all the workflow resources
249: * being assigned to activities, but should also return the
250: * additional workflow resources that are known to the resource
251: * assignment service.<P>
252: *
253: * If the resource assignment service is based on a resource
254: * management service as defined in package {@link
255: * de.danet.an.workflow.spis.rms
256: * <code>de.danet.an.workflow.spis.rms</code>}, it can simply
257: * delegate this call to {@link
258: * de.danet.an.workflow.spis.rms.ResourceManagementService#listResources
259: * <code>ResourceManagementService.listResources</code>}.
260: *
261: * The workflow engine does not need this method for its
262: * operation; however, it provides a method for accessing this
263: * information as part of the client interface to ease the
264: * implementation of clients. The implementation of this method by
265: * a resource assignment service is therefore optional. If not
266: * implemented, a call to this method must result in a {@link
267: * java.lang.UnsupportedOperationException
268: * <code>UnsupportedOperationException</code>}.<P>
269: *
270: * @return the collection of resources known to the resource
271: * assignment service (instances of {@link
272: * de.danet.an.workflow.omgcore.WfResource
273: * <code>WfResource</code>}).
274: * @throws RemoteException if a system-level error occurs.
275: */
276: Collection knownResources() throws RemoteException;
277:
278: /**
279: * Given a {@link de.danet.an.workflow.omgcore.WfResource
280: * <code>WfResource</code> object}, return the collection of
281: * resources this resource is authorized for.<P>
282: *
283: * The resource assignment service usually uses its underlying
284: * resource management facility to implement this method,
285: * returning all groups the resource is a member of and all roles
286: * assigned to the resource. Resource assigments facilities may,
287: * however, modify this information e.g. according to configured
288: * delegation rules.<P>
289: *
290: * If the resource assignment service is based on a resource
291: * management service as defined in package {@link
292: * de.danet.an.workflow.spis.rms
293: * <code>de.danet.an.workflow.spis.rms</code>}, it can simply
294: * delegate this call to {@link
295: * de.danet.an.workflow.spis.rms.ResourceManagementService#authorizers
296: * <code>ResourceManagementService.authorizers</code>}.
297: *
298: * The workflow engine does not need this method for its
299: * operation; however, it provides a method for accessing this
300: * information as part of the client interface to ease the
301: * implementation of clients. The implementation of this method by
302: * a resource assignment service is therefore optional. If not
303: * implemented, a call to this method must result in a {@link
304: * java.lang.UnsupportedOperationException
305: * <code>UnsupportedOperationException</code>}.<P>
306: *
307: * @param resource the resource.
308: * @return a collection of <code>WfResource</code> objects, not
309: * including <code>resource</code>
310: * @throws RemoteException if a system-level error occurs.
311: * @since 1.2
312: */
313: Collection authorizers(WfResource resource) throws RemoteException;
314:
315: /**
316: * Triggers the automatic assignment of resources to an activity that
317: * is about to become ready.<P>
318: *
319: * Usually, criteria for the resource selection must be determined within
320: * the resource assignment, e.g. based on the name of the activity,
321: * the process it belongs to etc. In some cases, however, the worflow
322: * component may have some resource selection information available. The
323: * workflow component may have obtained such information e.g. as part
324: * of the process description. If such information is available,
325: * it may optionally be passed to the automatic assignment. The
326: * type and valid values of such information depends totally
327: * on the resource assignment service used and remains undefined
328: * in the scope of this interface.<P>
329: *
330: * @param actId a unique (with respect to an <code>ActivityFinder</code>)
331: * identifier for the Activity. The length of <code>actId</code> is
332: * guaranteed not to exceed 64.
333: * @param finder the finder used to lookup activities by
334: * their <code>finderId</code>s.
335: * @param activity the activity that is about to become ready.
336: * @param principal the creator of the process, may be
337: * <code>null</code>.
338: * @param participant the <code>Participant</code> that describes
339: * resource selection criteria.
340: * The paramter may be <code>null</code>
341: * @return the assigned resources (instances of {@link
342: * de.danet.an.workflow.omgcore.WfResource
343: * <code>WfResource</code>}).
344: * @throws RemoteException if a system-level error occurs.
345: * @see ActivityFinder
346: */
347: Collection autoAssignResources(ActivityFinder finder, String actId,
348: WfActivity activity, Principal principal,
349: Participant participant) throws RemoteException;
350:
351: /**
352: * Change an assignment for enacting an activity. This method is
353: * called by the workflow engine in {@link
354: * de.danet.an.workflow.api.Activity#changeAssignment
355: * <code>Activity.changeAssignment</code>} which should be used by
356: * resource assignment services to implement
357: * <code>WfAssignment.setAssignee</code>.
358: *
359: * @param finder the finder used to lookup activities by
360: * their <code>finderId</code>s
361: * @param actId a unique (with respect to an <code>ActivityFinder</code>)
362: * identifier for the Activity. The length of <code>actId</code> is
363: * guaranteed not to exceed 64
364: * @param activity the activity being enacted
365: * @param oldResource the resource that has its assignment removed
366: * @param newResource the resource to be assigned
367: * @throws RemoteException if a system-level error occurs
368: * @throws InvalidResourceException if the resource is invalid.
369: * As the environment is a concurrent multi user environment,
370: * <code>WfResource</code> objects may become invalid
371: * @throws AlreadyAssignedException if the assignment already
372: * exists
373: * @throws NotAssignedException if there is no assignment to the
374: * old resource
375: * @see ActivityFinder
376: */
377: void changeAssignment(ActivityFinder finder, String actId,
378: WfActivity activity, WfResource oldResource,
379: WfResource newResource) throws RemoteException,
380: InvalidResourceException, AlreadyAssignedException,
381: NotAssignedException;
382:
383: /**
384: * Remove the assignment of a resource to an activity. This method
385: * is called by the workflow engine in {@link
386: * de.danet.an.workflow.api.Activity#removeAssignment
387: * <code>Activity.removeAssignment</code>} which, in turn, should
388: * be used by resource management services to implement
389: * <code>WfResource.release</code>.
390: *
391: * @param finder the finder used to lookup activities by
392: * their <code>finderId</code>s
393: * @param actId a unique (with respect to an <code>ActivityFinder</code>)
394: * identifier for the Activity. The length of <code>actId</code> is
395: * guaranteed not to exceed 64.
396: * @param activity the activity that is about to become ready
397: * @param resource the resource to be assigned
398: * @throws RemoteException if a system-level error occurs
399: * @throws InvalidResourceException if the resource is invalid.
400: * As the environment is a concurrent multi user environment,
401: * <code>WfResource</code> objects may become invalid.
402: * @throws NotAssignedException if the resource is not assigned to
403: * the given activity
404: * @see ActivityFinder
405: */
406: void removeAssignment(ActivityFinder finder, String actId,
407: WfActivity activity, WfResource resource)
408: throws RemoteException, InvalidResourceException,
409: NotAssignedException;
410:
411: /**
412: * Return the assignments to an activity.
413: *
414: * @param actId a unique (with respect to an <code>ActivityFinder</code>)
415: * identifier for the Activity. The length of <code>actId</code> is
416: * guaranteed not to exceed 64.
417: * @param finder the finder used to lookup activities by
418: * their <code>finderId</code>s.
419: * @param activity the activity.
420: * @return the collection of assignments (instances of
421: * {@link de.danet.an.workflow.omgcore.WfAssignment
422: * <code>WfAssignment</code>}).
423: * @throws RemoteException if a system-level error occurs.
424: */
425: Collection assignments(ActivityFinder finder, String actId,
426: WfActivity activity) throws RemoteException;
427:
428: /**
429: * Return the assignments of a given resource.
430: *
431: * @param resource the resource.
432: * @return the collection of assigned work items (instances of
433: * {@link de.danet.an.workflow.omgcore.WfAssignment
434: * <code>WfAssignment</code>}).
435: * @throws RemoteException if a system-level error occurs.
436: * @throws NoSuchResourceException if the resource is invalid.
437: * As the environment is a concurrent multi user environment,
438: * <code>WfResource</code> objects may become invalid.
439: */
440: Collection workItems(WfResource resource) throws RemoteException,
441: NoSuchResourceException;
442:
443: /**
444: * Find out if a given assignment belongs to the work items assigned to
445: * a particular resource.
446: *
447: * @param resource the resource.
448: * @param assignment the assignment in question.
449: * @return <code>true</code> if the <code>assignment</code> belongs to
450: * the work items of the <code>resource</code>.
451: * @throws RemoteException if a system-level error occurs.
452: * @throws NoSuchResourceException if the resource is invalid.
453: * As the environment is a concurrent multi user environment,
454: * <code>WfResource</code> objects may become invalid.
455: */
456: boolean isMemberOfWorkItems(WfResource resource,
457: WfAssignment assignment) throws RemoteException,
458: NoSuchResourceException;
459:
460: /**
461: * Get the resource associated with an Assignment.
462: *
463: * @param asnmnt the assignment
464: * @return the resource
465: * @throws RemoteException if a system-level error occurs.
466: * @since 1.3.4
467: */
468: WfResource getResource(WfAssignment asnmnt) throws RemoteException;
469:
470: }
|