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