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