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 */
013package com.ibm.rational.wvcm.stp.cq;
014
015import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
016
017import java.util.List;
018import java.util.Map;
019
020import javax.wvcm.WvcmException;
021import javax.wvcm.PropertyNameList.PropertyName;
022
023import com.ibm.rational.wvcm.stp.cq.CqProvider;
024import com.ibm.rational.wvcm.stpex.StpExEnumeration;
025import 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>&lt;record-type&gt;</i>/<i>&lt;action-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
040 * </pre>
041 */
042
043public 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}