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>&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    
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    }