001 /*
002 * file CqAction.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqAction
008 *
009 * (C) Copyright IBM Corporation 2004, 2008. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013 package com.ibm.rational.wvcm.stp.cq;
014
015 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016
017 import java.util.List;
018 import java.util.Map;
019
020 import javax.wvcm.WvcmException;
021 import javax.wvcm.PropertyNameList.PropertyName;
022
023 import com.ibm.rational.wvcm.stp.cq.CqProvider;
024 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
025 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
026
027 /**
028 * An object that represents a method to be applied to an {@link CqRecord}.
029 * <p>
030 * The set of CqActions applicable to a CqRecord can be obtained from its
031 * CqRecordType resource. (See
032 * {@link CqRecordType#ACTION_LIST CqRecordType.ACTION_LIST})
033 * <p>
034 * Some Actions require additional arguments when they are applied to an Record.
035 * These will be documented in the description of the action types.
036 * <p>
037 * The user-friendly specification for the location of an action has the form
038 * <pre>
039 * <b>cq.action:</b><i><record-type></i>/<i><action-name></i>@<i><db-set></i>/<i><user-db></i>
040 * </pre>
041 */
042
043 public interface CqAction
044 extends CqUserDbMember
045 {
046
047 /**
048 * The type of an action, which places certain restrictions on its use.
049 */
050 public static enum Type
051 implements StpExEnumeration
052 {
053 /** When a value for this type is not defined. */
054 NIL,
055
056 /** This type of action creates a new record */
057 SUBMIT,
058
059 /**
060 * This type of action changes an existing record without changing its
061 * state
062 */
063 MODIFY,
064
065 /**
066 * This type of action changes the state of a record (and other fields,
067 * too)
068 */
069 CHANGE_STATE,
070
071 /**
072 * This type of action marks a record as a duplicate of another.
073 * <p>
074 * Note. This type of action requires an argument named "original". The
075 * value of this argument must be a proxy for the record that has been
076 * duplicated.
077 */
078 DUPLICATE,
079
080 /** This type of action removes the DUPLICATE attribute from a record. */
081 UNDUPLICATE,
082
083 /**
084 * This type of action creates a new record whose content has been
085 * import from another database
086 */
087 IMPORT,
088
089 /**
090 * This type of action physically removes a record from the database, as
091 * opposed to putting it into a "deleted" state. Actions of this type
092 * may only be used with CqRecord.doUnbindAll. Once this action is
093 * started, the targeted record is no longer accessible in its change
094 * context unless the change context is reverted.
095 */
096 DELETE,
097
098 /** This type of action is used for defining base hook programs */
099 BASE,
100
101 /**
102 * For this type of action, the entire body is specified by a
103 * record-script.
104 */
105 RECORD_SCRIPT_ALIAS,
106
107 /**
108 * This type of action copies a record with it's children, preserving
109 * the state of the record.
110 */
111 COPY,
112 ;
113 }
114
115 /**
116 * Returns the Map containing the argument name/value pairs for by this
117 * Action.
118 *
119 * @return The argument/value Map defined for this action. Will be <b>null</b>
120 * if no such Map has been established.
121 */
122 Map<String, Object> argumentMap();
123
124 /**
125 * Sets any arguments needed when applying this action to an actionable
126 * resource.
127 *
128 * @param args A Map associating each argument name with its corresponding
129 * value. May be <b>null</b> or empty if this action does not
130 * require any arguments.
131 */
132 void argumentMap(Map<String, Object> args);
133
134 /**
135 * The {@link Type Type} of this action.
136 */
137 PropertyName<Type> TYPE = new PropertyName<Type>(PROPERTY_NAMESPACE, "type");
138
139 /**
140 * Returns the value of the {@link #TYPE TYPE} property as defined by this
141 * proxy.
142 *
143 * @return A Type enumerator identifying the type of this action.
144 *
145 * @throws WvcmException if this proxy does not define a value for the
146 * {@link #TYPE TYPE} property.
147 */
148 public Type getType() throws WvcmException;
149
150 /**
151 * The name of the state that a record will be in upon successful
152 * application of this action to the record.
153 */
154 PropertyName<String> DESTINATION_STATE =
155 new PropertyName<String>(PROPERTY_NAMESPACE,
156 "destination-state");
157
158 /**
159 * Returns the value of the {@link #DESTINATION_STATE DESTINATION_STATE}
160 * property as defined by this proxy.
161 *
162 * @return A String naming the state in which this action leaves a record
163 * when successfully applied to that record; an empty string if
164 * this action is not a CHANGE_STATE action.
165 *
166 * @throws WvcmException if this proxy does not define a value for the
167 * {@link #DESTINATION_STATE DESTINATION_STATE}
168 * property.
169 */
170 public String getDestinationState() throws WvcmException;
171
172 /** The record type with which this action is associated. */
173 PropertyName<CqRecordType> RECORD_TYPE =
174 new PropertyName<CqRecordType>(PROPERTY_NAMESPACE,
175 "record-type");
176
177 /**
178 * Returns the value of the {@link #RECORD_TYPE RECORD_TYPE} property as
179 * defined by this proxy.
180 *
181 * @return A CqRecordType proxy for the record type with which this action is
182 * associated.
183 *
184 * @throws WvcmException if this proxy does not define a value for the
185 * {@link #RECORD_TYPE RECORD_TYPE} property.
186 */
187 public CqRecordType getRecordType() throws WvcmException;
188
189 /** A list of the states a record must be in to apply this action to it. */
190 PropertyName<List<String>> SOURCE_STATE_LIST =
191 new PropertyName<List<String>>(PROPERTY_NAMESPACE, "source-state-list");
192
193 /**
194 * Returns the value of the {@link #SOURCE_STATE_LIST SOURCE_STATE_LIST}
195 * property as defined by this proxy.
196 *
197 * @return A list of Strings, each containing the name of a state in which
198 * this action may be applied; an empty list if the action is not
199 * a CHANGE_STATE action.
200 *
201 * @throws WvcmException if this proxy does not define a value for the
202 * {@link #SOURCE_STATE_LIST SOURCE_STATE_LIST}
203 * property.
204 */
205 public List<String> getSourceStateList() throws WvcmException;
206 }