OnParentVersionAction


1   /*
2    * $Id: OnParentVersionAction.java,v 1.3 2004/07/31 11:49:26 benjmestrallet Exp $
3    *
4    * Copyright 2002-2004 Day Management AG, Switzerland.
5    *
6    * Licensed under the Day RI License, Version 2.0 (the "License"),
7    * as a reference implementation of the following specification:
8    *
9    *   Content Repository API for Java Technology, revision 0.12
10   *        <http://www.jcp.org/en/jsr/detail?id=170>
11   *
12   * You may not use this file except in compliance with the License.
13   * You may obtain a copy of the License files at
14   *
15   *     http://www.day.com/content/en/licenses/day-ri-license-2.0
16   *     http://www.apache.org/licenses/LICENSE-2.0
17   *
18   * Unless required by applicable law or agreed to in writing, software
19   * distributed under the License is distributed on an "AS IS" BASIS,
20   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21   * See the License for the specific language governing permissions and
22   * limitations under the License.
23   */
24  package javax.jcr.version;
25  
26  /**
27   * The possible actions specified by the <code>onParentVersion</code> attribute
28   * in a property definition within a node type definition.
29   * <p/>
30   * <b>Level 2 only</b>
31   * <p/>
32   * This interface defines the following actions:
33   * <UL>
34   * <LI>COPY
35   * <LI>VERSION
36   * <LI>INITIALIZE
37   * <LI>COMPUTE
38   * <LI>IGNORE
39   * <LI>ABORT
40   * </UL>
41   * <p/>
42   * Every item (node or property) in the repository has a status indicator that
43   * governs what happens to that item when its parent node is versioned. This
44   * status is defined by the onParentVersion attribute in the PropertyDefNT or
45   * NodeDef that applies to the item in question. This PropertyDefNT or NodeDef is
46   * part of the NodeType of the parent node of the item in question.
47   * <p/>
48   * For example, let N be a versionable node in workspace W of repository R.
49   * Furthermore, let N be of node type T, where T is a sub-type of
50   * nt:versionable and T allows N to have one property called P and one child
51   * node called C.
52   * <p/>
53   * What happens to P and C when N is versioned depends on their respective
54   * OnParentVersion attribute as defined in the PropertyDefNT for P and the
55   * NodeDef for C, found in the definition of node type T.
56   * <p/>
57   * The possible values for the OnParentVersion attribute are: COPY, VERSION,
58   * INITIALIZE, COMPUTE, NOTHING and FORBIDDEN.
59   * <p/>
60   * The sections below describe, for each possible value of the OnParentVersion
61   * attribute, what happens to C and P when,
62   * <ul>
63   * <li>N.checkin() is performed, creating the new version VN and adding to the
64   * version history.
65   * <li>N.restore(VN)  is performed, restoring the version VN.
66   * </ul>
67   * <p/>
68   * COPY
69   * <p/>
70   * Child Node
71   * <p/>
72   * On checkin of N, C and all its descendent items, down to the leaves of the
73   * subtree, will be copied to the version storage as a child subtree of VN. The
74   * copy of C and its subtree will not have its own version history but will be
75   * part of the state preserved in VN. C itself need not be versionable.
76   * <p/>
77   * On restore of VN, the copy of C and its subtree stored will be restored as
78   * well, replacing the current C and its subtree in the workspace.
79   * <p/>
80   * Property
81   * <p/>
82   * On checkin of N, P will be copied to the version storage as a child of VN.
83   * This copy of P is part of the state preserved in VN.
84   * <p/>
85   * On restore of VN, the copy of P stored as its child will be restored as
86   * well, replacing the current P in the workspace.
87   * <p/>
88   * VERSION
89   * <p/>
90   * Child Node
91   * <p/>
92   * On checkin of N, the node VN will get a child reference to the version
93   * history of C (not to C or any actual version of C). In practice, this means
94   * that the root version of C's version history becomes the child of VN
95   * because, as mentioned before, the root version is used as the referent when
96   * a reference to the version history as a whole is required. This also
97   * requires that C itself be versionable (otherwise it would not have a version
98   * history). If C is not versionable then behavior of IGNORE applies on checkin
99   * (see below).
100  * <p/>
101  * On restore of VN, if the workspace currently has an already existing node
102  * corresponding to C's version history, then that instance of C becomes the
103  * child of the restored N. If the workspace does not have an instance of C
104  * then one is restored from C's version history. The workspace in which the
105  * restore is being performed will determine which particular version of C will
106  * be restored. This determination depends on the configuration of the
107  * workspace and is outside the scope of this specification.
108  * <p/>
109  * Property
110  * <p/>
111  * In the case of properties, an OnParentVersion attribute of VERSION has the
112  * same effect as COPY.
113  * <p/>
114  * INITIALIZE
115  * <p/>
116  * Child Node
117  * <p/>
118  * On checkin of N, a new node C will be created and placed in version storage
119  * as a child of VN. This new C will be initialized just as it would be if
120  * created normally in a workspace. No state information of the current C in
121  * the workspace is preserved. The new C will not have its own version history
122  * but will be part of the state preserved in VN. C itself need not be
123  * versionable.
124  * <p/>
125  * On restore of VN, the C stored as its child will be restored as well,
126  * replacing the current C in the workspace.
127  * <p/>
128  * Property
129  * <p/>
130  * On checkin of N, a new P will be created and placed in version storage as a
131  * child of VN. The new P will be initialized just as it would be if created
132  * normally in a workspace. The new P is part of the state preserved in VN.
133  * <p/>
134  * On restore of VN, the P stored as its child will be restored as well,
135  * replacing the current P in the workspace.
136  * <p/>
137  * COMPUTE
138  * <p/>
139  * Child Node
140  * <p/>
141  * On checkin of N, a new node C will be created and placed in version storage
142  * as a child of VN. This new C will be initialized according to some
143  * configuration-specific procedure beyond the scope of this specification. The
144  * new C will not have its own version history but will be part of the state
145  * preserved in VN. C itself need not be versionable.
146  * <p/>
147  * On restore of VN, the C stored as its child will be restored as well,
148  * replacing the current C in the workspace.
149  * <p/>
150  * Property
151  * <p/>
152  * On checkin of N, a new P will be created and placed in version storage as a
153  * child of VN. The new P will be initialized according to some
154  * configuration-specific procedure beyond the scope of this specification. The
155  * new P is part of the state preserved in VN.
156  * <p/>
157  * On restore of VN, the P stored as its child will be restored as well,
158  * replacing the current P in the workspace.
159  * <p/>
160  * IGNORE
161  * <p/>
162  * Child Node
163  * <p/>
164  * On checkin of N, no state information about C will be stored in VN.
165  * <p/>
166  * On restore of VN, the child node C of the current N will remain and not be
167  * removed, despite not being included in the state recorded in VN, since its
168  * IGNORE status tells the system to leave it alone.
169  * <p/>
170  * Property
171  * <p/>
172  * On checkin of N, no state information about P will be stored in VN.
173  * <p/>
174  * On restore of VN, the property P of the current N will remain and not be
175  * removed, despite not being included in the state of recorded in VN, since
176  * its IGNORE status tells the system to leave it alone.
177  * <p/>
178  * ABORT
179  * <p/>
180  * Child Node or Property
181  * <p/>
182  * On checkin of N an exception will be thrown. Having a child node or property
183  * with an OnParentVersion attribute of ABORT prevents the parent node from
184  * being checked-in.
185  *
186  * @author Peeter Piegaze
187  * @author Stefan Guggisberg
188  */
189 public final class OnParentVersionAction {
190 
191   /**
192    * The action constants.
193    */
194   public static final int COPY = 1;
195   public static final int VERSION = 2;
196   public static final int INITIALIZE = 3;
197   public static final int COMPUTE = 4;
198   public static final int IGNORE = 5;
199   public static final int ABORT = 6;
200 
201   /**
202    * The names of the defined on-version actions,
203    * as used in serialization.
204    */
205   public static final String   ACTIONNAME_COPY = "COPY";
206   public static final String   ACTIONNAME_VERSION = "VERSION";
207   public static final String   ACTIONNAME_INITIALIZE = "INITIALIZE";
208   public static final String   ACTIONNAME_COMPUTE = "COMPUTE";
209   public static final String   ACTIONNAME_IGNORE = "IGNORE";
210   public static final String   ACTIONNAME_ABORT = "ABORT";
211 
212   /**
213    * Returns the name of the specified <code>action</code>,
214    * as used in serialization.
215    *
216    * @param action the on-version action
217    * @return the name of the specified <code>action</code>
218    * @throws IllegalArgumentException if <code>action</code>
219    *                                  is not a valid on-version action.
220    */
221   public static String   nameFromValue(int action) {
222     switch (action) {
223       case COPY:
224         return ACTIONNAME_COPY;
225       case VERSION:
226         return ACTIONNAME_VERSION;
227       case INITIALIZE:
228         return ACTIONNAME_INITIALIZE;
229       case COMPUTE:
230         return ACTIONNAME_COMPUTE;
231       case IGNORE:
232         return ACTIONNAME_IGNORE;
233       case ABORT:
234         return ACTIONNAME_ABORT;
235       default:
236         throw new IllegalArgumentException  ("unknown on-version action: " + action);
237     }
238   }
239 
240   /**
241    * Returns the numeric constant value of the on-version action with the
242    * specified name.
243    *
244    * @param name the name of the on-version action
245    * @return the numeric constant value
246    * @throws IllegalArgumentException if <code>name</code>
247    *                                  is not a valid on-version action name.
248    */
249   public static int valueFromName(String   name) {
250     if (name.equals(ACTIONNAME_COPY)) {
251       return COPY;
252     } else if (name.equals(ACTIONNAME_VERSION)) {
253       return VERSION;
254     } else if (name.equals(ACTIONNAME_INITIALIZE)) {
255       return INITIALIZE;
256     } else if (name.equals(ACTIONNAME_COMPUTE)) {
257       return COMPUTE;
258     } else if (name.equals(ACTIONNAME_IGNORE)) {
259       return IGNORE;
260     } else if (name.equals(ACTIONNAME_ABORT)) {
261       return ABORT;
262     } else {
263       throw new IllegalArgumentException  ("unknown on-version action: " + name);
264     }
265   }
266 
267   /**
268    * private constructor to prevent instantiation
269    */
270   private OnParentVersionAction() {
271   }
272 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags