001: /*
002: * Copyright 2005-2006 The Kuali Foundation.
003: *
004: *
005: * Licensed under the Educational Community License, Version 1.0 (the "License");
006: * you may not use this file except in compliance with the License.
007: * You may obtain a copy of the License at
008: *
009: * http://www.opensource.org/licenses/ecl1.php
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package edu.iu.uis.eden.plugin.attributes;
018:
019: import java.util.List;
020:
021: import edu.iu.uis.eden.EdenConstants;
022: import edu.iu.uis.eden.Id;
023: import edu.iu.uis.eden.engine.RouteContext;
024: import edu.iu.uis.eden.exception.EdenUserNotFoundException;
025: import edu.iu.uis.eden.routeheader.DocumentContent;
026: import edu.iu.uis.eden.routetemplate.ResolvedQualifiedRole;
027: import edu.iu.uis.eden.routetemplate.Role;
028:
029: /**
030: * A special type of attribute that is used exclusively for resolving abstract roles
031: * to concrete responsibilities (users and groups). A RoleAttribute provides resolution
032: * for a set of abstract "role" names. These are published via the {@link #getRoleNames()}
033: * method, which returns a list of {@link Role}, which is a combination of class name (attribute implementation class),
034: * abstract role name, and optional label and return url (DOCME: what is return url used for?).
035: *
036: * <p>RoleAttribute lifecycle:
037: * <ol>
038: * <li>A RoleAttribute is defined on a Rule, via the <code>role</code> element, with the syntax:
039: * <i>fully qualified class name</i><b>!</b><i>abstract role name</i>. E.g.:<br/>
040: * <blockquote><code><role>edu.whatever.attribute.SomeAttribute!RoleName</role></code></blockquote>
041: * </li>
042: * <li>When the <code><role></code> element is parsed, the Rule's "responsibility" is set to the role element value
043: * and the responsibility is marked to indicate that it is a role ("R", {@link EdenConstants#RULE_RESPONSIBILITY_ROLE_ID})</li>
044: * <li>When a Rule that is configured with a Role responsibility is fired, {@link #getQualifiedRoleNames(String, DocumentContent)}
045: * is called to return a list of "qualified" role names. Qualified role names are role names which have been qualified
046: * with some relevant contextual information (e.g. from the document) that is useful for subsequent responsibility
047: * resolution.</li>
048: * <li>{@link #resolveQualifiedRole(RouteContext, String, String)} is immediately called for each of the qualified role names
049: * returned in the previous step, and it returns a {@link ResolvedQualifiedRole} containing the
050: * list of concrete recipients ({@link Id}s).</li>
051: * <li>({@link edu.iu.uis.eden.routetemplate.UnqualifiedRoleAttribute} base class can be used to simplify this
052: * two-step process)</li>
053: * </ol>
054: *
055: * <p>Relationship to WorkflowAttribute: all RoleAttribute implementations are also
056: * WorkflowAttribute implementations (is this true? should RoleAttribute extend WorkflowAttribute in that case?)
057: *
058: * <p>Methods of WorkflowAttribute interface fulfilled by RoleAttribute:
059: * <ol>
060: * <li>??</li>
061: * </ol>
062: * Methods of WorkflowAttribute interface not relevant to RoleAttribute:
063: * <ol>
064: * <li>{@link WorkflowAttribute#isMatch(DocumentContent, List)}</li>
065: * <li>??</li>
066: * </ol>
067: *
068: * @see WorkflowAttribute
069: *
070: * @author rkirkend
071: */
072: public interface RoleAttribute {
073:
074: /**
075: * List of {@link Role}s this RoleAttribute supports
076: * @return list of {@link Role}s this RoleAttribute supports
077: */
078: public List<Role> getRoleNames();
079:
080: /**
081: * Returns a String which represent the qualified role name of this role for the given
082: * roleName and docContent.
083: * @param roleName the role name (without class prefix)
084: * @param documentContent the document content
085: * @throws EdenUserNotFoundException
086: */
087: public List<String> getQualifiedRoleNames(String roleName,
088: DocumentContent documentContent)
089: throws EdenUserNotFoundException;
090:
091: /**
092: * Returns a List of Workflow Users which are members of the given qualified role.
093: * @param routeContext the RouteContext
094: * @param roleName the roleName (without class prefix)
095: * @param qualifiedRole one of the the qualified role names returned from the {@link #getQualifiedRoleNames(String, DocumentContent)} method
096: * @return ResolvedQualifiedRole containing recipients, role label (most likely the roleName), and an annotation
097: */
098: public ResolvedQualifiedRole resolveQualifiedRole(
099: RouteContext routeContext, String roleName,
100: String qualifiedRole) throws EdenUserNotFoundException;
101:
102: }
|