1 /*
2 * Copyright 2005-2007 The Kuali Foundation
3 *
4 *
5 * Licensed under the Educational Community License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.opensource.org/licenses/ecl2.php
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.kuali.rice.kew.rule;
18
19 import java.util.List;
20
21 import org.kuali.rice.kew.engine.RouteContext;
22 import org.kuali.rice.kew.identity.Id;
23 import org.kuali.rice.kew.routeheader.DocumentContent;
24 import org.kuali.rice.kew.util.KEWConstants;
25
26
27 /**
28 * A special type of attribute that is used exclusively for resolving abstract roles
29 * to concrete responsibilities (users and groups). A RoleAttribute provides resolution
30 * for a set of abstract "role" names. These are published via the {@link #getRoleNames()}
31 * method, which returns a list of {@link Role}, which is a combination of class name (attribute implementation class),
32 * abstract role name, and optional label and return url (DOCME: what is return url used for?).
33 *
34 * <p>RoleAttribute lifecycle:
35 * <ol>
36 * <li>A RoleAttribute is defined on a Rule, via the <code>role</code> element, with the syntax:
37 * <i>fully qualified class name</i><b>!</b><i>abstract role name</i>. E.g.:<br/>
38 * <blockquote><code><role>edu.whatever.attribute.SomeAttribute!RoleName</role></code></blockquote>
39 * </li>
40 * <li>When the <code><role></code> element is parsed, the Rule's "responsibility" is set to the role element value
41 * and the responsibility is marked to indicate that it is a role ("R", {@link KEWConstants#RULE_RESPONSIBILITY_ROLE_ID})</li>
42 * <li>When a Rule that is configured with a Role responsibility is fired, {@link #getQualifiedRoleNames(String, DocumentContent)}
43 * is called to return a list of "qualified" role names. Qualified role names are role names which have been qualified
44 * with some relevant contextual information (e.g. from the document) that is useful for subsequent responsibility
45 * resolution.</li>
46 * <li>{@link #resolveQualifiedRole(RouteContext, String, String)} is immediately called for each of the qualified role names
47 * returned in the previous step, and it returns a {@link ResolvedQualifiedRole} containing the
48 * list of concrete recipients ({@link Id}s).</li>
49 * <li>({@link org.kuali.rice.kew.rule.UnqualifiedRoleAttribute} base class can be used to simplify this
50 * two-step process)</li>
51 * </ol>
52 *
53 * <p>Relationship to WorkflowAttribute: all RoleAttribute implementations are also
54 * WorkflowAttribute implementations (is this true? should RoleAttribute extend WorkflowAttribute in that case?)
55 *
56 * <p>Methods of WorkflowAttribute interface fulfilled by RoleAttribute:
57 * <ol>
58 * <li>??</li>
59 * </ol>
60 * Methods of WorkflowAttribute interface not relevant to RoleAttribute:
61 * <ol>
62 * <li>{@link WorkflowAttribute#isMatch(DocumentContent, List)}</li>
63 * <li>??</li>
64 * </ol>
65 *
66 * @see WorkflowAttribute
67 *
68 * @author Kuali Rice Team (rice.collab@kuali.org)
69 */
70 public interface RoleAttribute {
71
72 /**
73 * List of {@link Role}s this RoleAttribute supports
74 * @return list of {@link Role}s this RoleAttribute supports
75 */
76 public List<Role> getRoleNames();
77
78 /**
79 * Returns a String which represent the qualified role name of this role for the given
80 * roleName and docContent.
81 * @param roleName the role name (without class prefix)
82 * @param documentContent the document content
83 */
84 public List<String> getQualifiedRoleNames(String roleName, DocumentContent documentContent);
85
86 /**
87 * Returns a List of Workflow Users which are members of the given qualified role.
88 * @param routeContext the RouteContext
89 * @param roleName the roleName (without class prefix)
90 * @param qualifiedRole one of the the qualified role names returned from the {@link #getQualifiedRoleNames(String, DocumentContent)} method
91 * @return ResolvedQualifiedRole containing recipients, role label (most likely the roleName), and an annotation
92 */
93 public ResolvedQualifiedRole resolveQualifiedRole(RouteContext routeContext, String roleName, String qualifiedRole);
94
95 }