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.io.Serializable;
020: import java.util.List;
021: import java.util.Map;
022:
023: import edu.iu.uis.eden.EdenConstants;
024: import edu.iu.uis.eden.clientapp.vo.WorkflowAttributeDefinitionVO;
025: import edu.iu.uis.eden.lookupable.Row;
026: import edu.iu.uis.eden.routeheader.DocumentContent;
027: import edu.iu.uis.eden.routetemplate.RuleExtension;
028: import edu.iu.uis.eden.routetemplate.RuleExtensionValue;
029: import edu.iu.uis.eden.routetemplate.xmlrouting.GenericXMLRuleAttribute;
030:
031: /**
032: * <p>Interface which abstracts a piece of information ("attribute") associated with
033: * a Workflow document, which can be used to make routing decisions when combined
034: * with Rules.</p>
035: * <p>WorkflowAttribute lifecycle:</p>
036: * <p>Definition via XML</p>
037: * <ol>
038: * <li>Attribute definition is defined in XML (... any actions that are performed on-definition)</li>
039: * <li>Attribute definition is registered in a Rule Template definition in XML</li>
040: * <li>Rule Template is associated with a Document and a Rule in XML</li>
041: * </ol>
042: * <p>Definition via UI (this documentation needs work)</p>
043: * <ol>
044: * <li>...?...</li>
045: * <li>{@link #validateRuleData(Map)} and {@link #validateRoutingData(Map)} and are called to validate the configuration/extension values
046: * of the rule definition, and the user-configured rule data (??). see {@link edu.iu.uis.eden.routetemplate.web.WebRuleBaseValues},
047: * {@link edu.iu.uis.eden.routetemplate.RuleRoutingAttribute}.</li>
048: * <li>Not sure where and why these are called, or how that is reconciled with XML-based ingestion....? The 'required' field only seems
049: * to matter with regard to these two methods; it seems to only ever be used in implementations of these two methods</li>
050: * </ol>
051: * <p>Runtime evaluation</p>
052: * <ol>
053: * <li>Client application constructs {@link edu.iu.uis.eden.clientapp.vo.WorkflowAttributeDefinitionVO} and attaches
054: * it to the client-side document</li>
055: * <li>Upon action taken on the document, the Attributes that are described by the <code>WorkflowAttributeDefinitionVO</code>s
056: * are looked up (... how ...) and constructed on the client side.</li>
057: * <li>If the attribute is a {@link WorkflowAttributeXmlValidator} (e.g. {@link edu.iu.uis.eden.routetemplate.xmlrouting.StandardGenericXMLRuleAttribute}),
058: * then {@link WorkflowAttributeXmlValidator#validateClientRoutingData()} is called to validate any data the client app may have set
059: * on the client-instantiated attribute (the {@link edu.iu.uis.eden.clientapp.vo.WorkflowAttributeDefinitionVO})</li>
060: * <li>Attribute content (content the attribute generates to place in the eDoc document content) is obtained from the attribute
061: * via {@link WorkflowAttribute#getDocContent()} or {@link edu.iu.uis.eden.docsearch.SearchableAttribute#getSearchContent()},
062: * depending on whether the attribute is a WorkflowAttribute or {@link edu.iu.uis.eden.docsearch.SearchableAttribute}</li>
063: * <li>When a Rule is invoked (for instance, when a <code>requests</code> node is fired), all attributes associated with the rule
064: * (those associated with the Rule Template associated with the rule) which are WorkflowAttributes are enumerated and for each:
065: * <ol>
066: * <li>A special case is made for attributes defined in XML as
067: * of "RuleXmlAttribute" type ({@link EdenConstants#RULE_XML_ATTRIBUTE_TYPE}): the attribute is cast to {@link GenericXMLRuleAttribute}
068: * and RuleAttribute business object is set on it ({@link GenericXMLRuleAttribute#setRuleAttribute(edu.iu.uis.eden.routetemplate.RuleAttribute)}
069: * before proceeding with isMatch invocation. (what about a RuleAttributeAware interface so this can be done generically for all worklfow attribute
070: * implementations?)</li>
071: * <li>{@link WorkflowAttribute#isMatch(DocumentContent, List)} is called with the Rule's extension values passed</li>
072: * </ol>
073: * </li>
074: * <li>If all attributes for the rule match, the rule is fired</li>
075: * </ol>
076: *
077: * @see WorkflowAttributeDefinitionVO
078: *
079: * @author rkirkend
080: */
081: public interface WorkflowAttribute extends Serializable {
082:
083: /**
084: * Returns true if this Attribute finds a match in the given DocContent. If true,
085: * the associated document will be routed to the users specifed by the UNF
086: *
087: * The isMatch method is responsible for determining whether content in a document matches content saved in workflow, thus determining whether to fire a rule or not.
088: * The isMatch method takes a DocumentContent object and a list of rule extension objects and returns a Boolean. The DocumentContent object contains the data in XML
089: * format that will be compared with the rules saved in workflow. Rule extension objects come from a potential rule that may match the document content on this eDoc.
090: * The potential rule is selected based on the Document Type and Rule Templates associated with this eDoc. Each rule extension object contains a list of rule extension
091: * value objects which have the data we will use in key value format to compare to the document content. The key will be determined by a unique string assigned by this
092: * attribute. The Value is determined when a rule is created and data is entered for the particular key. If a match is found, this method returns true and the eDoc will
093: * be routed based on this rule. If no match is found, the method returns false and the eDoc will not be routed based on this rule.
094: */
095: public boolean isMatch(DocumentContent docContent,
096: List<RuleExtension> ruleExtensions);
097:
098: /**
099: * Each Row contains Fields describing the UI-level presentation of a single RuleExtensionValue.
100: * <p>
101: * A single Row may contain more than one actual Field instance, but Fields beyond the first one
102: * are there to provide context for the display and evaluation of the first one.
103: *
104: * The getRuleRows method returns a list of rows that contain Fields describing the UI-level presentation of a single RuleExtensionValue for the creation of a rule.
105: * A single row may contain more than one actual Field object, but Fields beyond the first one are there to provide context for the display and evaluation of the first one.
106: * For example, a secondary field may be a lookupable or a searchable valid values object. An individual field consists of a field label, a field help url, a field type,
107: * whether a lookupable is associated with this field, a property name, a property value, valid values, the name of the lookupable, and the default lookupable name for this field.
108: * The field label is a short title that will display on the jsp describing what data to enter for this field. The field help url is optional, but will pop open in a new window
109: * the url entered. The field type is the type of field to display (e.g. hidden, text, drop down, radio, quickfinder (lookupable), lookup result only (this type is needed for
110: * the lookupable, but does not actually render on the jsp), and finally drop down refresh (this type is a drop down box that when it's value changes another drop down box's
111: * valid values will be changed as well)). The lookupable indicator determines whether this field will have a lookupable (valid value search) associated with it. The property
112: * name is the name of the field when rendered on the jsp. This needs to be unique when compared to other field names on the jsp. The property value is the value entered into
113: * the text box or other field type on the jsp. This value will be empty when creating the field and populated during form submission. A List of valid values is optional and
114: * needed to populate drop down boxes or radio buttons. This list consists of KeyLabelPair objects which the key will be the value passed in on submission and the label will
115: * be what is display on the jsp. The lookupable is the name of the lookable service to be called for this field. The default lookupable name is the name of the field on the
116: * lookupable itself. This may be the same of the property name of the field. This is needed when field conversions are needed. If the lookupable returns a key that doesn't
117: * match a property name on the jsp it needs to be converted to one that does. So if the property name is different than the default lookupable name, the lookupable will
118: * convert the return key to the property name of the field. Example: say by default a lookupable returns "color=red" on the url. The default lookupable name would be "color"
119: * and if you needed a different name for this property on the jsp such as "wallcolor", the lookupable will now return "wallcolor=red" instead of the default "color=red". The
120: * default lookupable name also is the key for rule extension values. When an extension value is saved the value comes from the UI and the key from this field. If this field
121: * is left null, then the property name of the field will become the key stored in the database for the extension value. A row can also consist of a group label and number
122: * of rows for this label to span for this attribute. If a group label is present, it will display on the rule creation jsp and group together the individual rows for this
123: * attribute. The total rows number will rowspan the group label across the rows of this attribute.
124: * NOTE: the group label and number of rows to span must be specified on each row object for the display to work correctly.
125: */
126: public List<Row> getRuleRows();
127:
128: /**
129: * RoutingDataRows contain Rows describing the UI-level presentation of the ruleData fields
130: * used to determine where a given document would be routed according to the associated rule.
131: *
132: * The getRoutingDataRows method returns a list of rows that contain Fields describing the UI-level presentation of a single RuleExtensionValue for the routing report feature.
133: * These rows are used to determine where an eDoc would route if these values were entered. They are constructed the same way rule rows are described above and a lot of times
134: * are identical.
135: */
136: public List<Row> getRoutingDataRows();
137:
138: /**
139: * Returns a String containing this Attribute's routingData values, formatted as a series of XML
140: * tags. The returned tags need not be contained within a single top-level tag.
141: * <p>
142: * For example, DollarRangeAttribute returns a single tag containing its totalDollarAmount, thus:
143: * <pre>
144: * <totalDollarAmount>345</totalDollarAmount>
145: * </pre>
146: */
147: public String getDocContent();
148:
149: /**
150: * Returns the List of RuleExtensionValue objects associated with this Rule, each of which contains
151: * the name and value of one of the parameters used by this Attribute to control when the associated
152: * Rule gets evaluated. RuleExtensionValues are assigned when the Rule is created.
153: * <p>
154: * For example, the DollarRangeAttribute has two associated RuleExtensionValues - its minimum and
155: * maximum values - which control when a rule containing that attribute gets evaluated.
156: * <p>
157: * The UI instantiates a Rule from a RuleTemplate, uses the RuleRows of all of that Rule's Attributes
158: * to build a form, uses user input to create a set of RuleExtensionValues which get persisted when
159: * the rule is persisted.
160: *
161: * To create a RuleExtensionValue object, instantiate a new object, set the key which will be located on the Rule's attribute,
162: * set the value which will be entered on the form from the UI side, and finally add each RuleExtensionValue object to a list.
163: *
164: *
165: * (Basically, given a configured/initialized attribute, marshalls out the RuleExtensionValues representing the current state of
166: * the attribute - Aaron Hamid FIXME)
167: */
168: public List<RuleExtensionValue> getRuleExtensionValues();
169:
170: /**
171: * Validates routingData values in the incoming map. Called by the UI during rule creation.
172: *
173: * This method is responsible for validating and setting the data entered on the form from the UI of the routing report to the Rule's attribute.
174: * The values will be in a Map with the key being the key of the RuleExtensionValue and the value being the value of the data entered from the
175: * UI. This method is used for the routing report which may have different fields than the rule data.
176: *
177: * @param parmaMap Map containing the names and values of the routing data for this Attribute
178: */
179: public List validateRoutingData(Map paramMap);
180:
181: /**
182: * Validates ruleExtension values in the incoming map. Called by the UI during rule creation.
183: *
184: * This method is responsible for validating and setting the data entered on the form from the UI of the rule creation to the Rule's attribute.
185: * The values will be in a Map with the key being the key of the RuleExtensionValue and the value being the value of the data entered from the UI.
186: * This method is used for rule creation which may have different fields than the routing report data.
187: *
188: * @param paramMap Map containing the names and values of the rule extensions for this Attribute
189: */
190: public List validateRuleData(Map paramMap);
191:
192: /**
193: * Sets the required flag for this Attribute to true. If required is true, the extensionValues for
194: * this Attribute must be filled in before the associated Rule can be persisted.
195: *
196: * This method sets a flag on whether this attribute is required or not.
197: * When a rule template is created, the rule's attribute can be required.
198: * This setting is then passed to the attribute by this method and can be used by the validateRuleData or validateRoutingData method as fit.
199: */
200: public void setRequired(boolean required);
201:
202: /**
203: * Returns true if the extensionValues on this Attribute must be filled in before the associated
204: * Rule can be persisted.
205: */
206: public boolean isRequired();
207:
208: /**
209: * Indicates to workflow Attribute that the flexreport is being done by the document type
210: * and not the route template
211: *
212: * This method is used to retrieve whether or not this method is required. It will return true if the ruleExtensionValues are required and false otherwise.
213: *
214: * @param inDocTypeReport
215: */
216: // public void setDoctypeReporting(boolean inDocTypeReport);
217: }
|