1 /*
2 * Copyright 1999-2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.commons.workflow;
18
19
20 /**
21 * <p>A <strong>Descriptor</strong> is a description of the mechanism by which
22 * an arbitrary Java object (typically a JavaBean) is referenced. The
23 * following reference methods are supported, and are processed in the
24 * order specified here:</p>
25 * <ul>
26 * <li>If the <code>xpath</code> property is set, it is used as an XPath
27 * expression identifying the requested object.</li>
28 * <li>If the <code>name</code> (and optional <code>scope</code>) properties
29 * are specified, they are used to select a particular named bean,
30 * optionally found in a particular named scope.</li>
31 * <li>If none of the conditions above are satisfied, the top object on the
32 * evaluation stack of our current <code>Context</code> is consumed.</li>
33 * </ul>
34 *
35 * @version $Revision: 155475 $ $Date: 2005-02-26 13:31:11 +0000 (Sat, 26 Feb 2005) $
36 * @author Craig R. McClanahan
37 */
38
39 public interface Descriptor {
40
41
42 // ------------------------------------------------------------- Properties
43
44
45 /**
46 * Return the name of the Java object (in some scope) referenced by
47 * this Descriptor.
48 */
49 public String getName();
50
51
52 /**
53 * Set the name of the Java object (in some scope) referenced by
54 * this Descriptor.
55 *
56 * @param name The new object name
57 */
58 public void setName(String name);
59
60
61 /**
62 * Return the scope of the Java object referenced by this Descriptor.
63 */
64 public String getScope();
65
66
67 /**
68 * Set the scope of the Java object referenced by this Descriptor.
69 *
70 * @param scope The new scope name
71 */
72 public void setScope(String scope);
73
74
75 /**
76 * Return the optional Java class expected by this Descriptor.
77 */
78 public Class getType();
79
80
81 /**
82 * Set the optional Java class expected by this Descriptor.
83 *
84 * @param type The new expected type
85 */
86 public void setType(Class type);
87
88
89 /**
90 * Return the XPath expression used to access the Java object
91 * referenced by this Descriptor.
92 */
93 public String getXpath();
94
95
96 /**
97 * Set the XPath expression used to access the Java object
98 * referenced by this Descriptor.
99 *
100 * @param xpath The new XPath expression
101 */
102 public void setXpath(String xpath);
103
104
105 // --------------------------------------------------------- Public Methods
106
107
108 /**
109 * Return the value specified by this Descriptor from the specified
110 * Context. If there is no such value, return <code>null</code>.
111 *
112 * @param context Context from which to retrieve this value
113 */
114 public Object get(Context context);
115
116
117 /**
118 * <p>Call <code>get()</code> to retrieve the value specified by this
119 * Descriptor, and then return <code>true</code> if this value represents
120 * a positive result; otherwise return <code>false</code>.</p>
121 *
122 * @param context Context from which to retrieve this value
123 */
124 public boolean positive(Context context);
125
126
127 /**
128 * Store the value into the destination specified by this Descriptor
129 * in the specified Context, replacing any existing value.
130 *
131 * @param context Context into which to store this value
132 * @param value Object value to be stored
133 */
134 public void put(Context context, Object value);
135
136
137 /**
138 * Remove any existing value associated with this Descriptor from the
139 * specified Context.
140 *
141 * @param context Context from which to remove this value.
142 */
143 public void remove(Context context);
144
145
146 }