001 /*
002 * Copyright 1999-2001,2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.workflow;
018
019
020 /**
021 * <p>A <strong>Descriptor</strong> is a description of the mechanism by which
022 * an arbitrary Java object (typically a JavaBean) is referenced. The
023 * following reference methods are supported, and are processed in the
024 * order specified here:</p>
025 * <ul>
026 * <li>If the <code>xpath</code> property is set, it is used as an XPath
027 * expression identifying the requested object.</li>
028 * <li>If the <code>name</code> (and optional <code>scope</code>) properties
029 * are specified, they are used to select a particular named bean,
030 * optionally found in a particular named scope.</li>
031 * <li>If none of the conditions above are satisfied, the top object on the
032 * evaluation stack of our current <code>Context</code> is consumed.</li>
033 * </ul>
034 *
035 * @version $Revision: 155475 $ $Date: 2005-02-26 13:31:11 +0000 (Sat, 26 Feb 2005) $
036 * @author Craig R. McClanahan
037 */
038
039 public interface Descriptor {
040
041
042 // ------------------------------------------------------------- Properties
043
044
045 /**
046 * Return the name of the Java object (in some scope) referenced by
047 * this Descriptor.
048 */
049 public String getName();
050
051
052 /**
053 * Set the name of the Java object (in some scope) referenced by
054 * this Descriptor.
055 *
056 * @param name The new object name
057 */
058 public void setName(String name);
059
060
061 /**
062 * Return the scope of the Java object referenced by this Descriptor.
063 */
064 public String getScope();
065
066
067 /**
068 * Set the scope of the Java object referenced by this Descriptor.
069 *
070 * @param scope The new scope name
071 */
072 public void setScope(String scope);
073
074
075 /**
076 * Return the optional Java class expected by this Descriptor.
077 */
078 public Class getType();
079
080
081 /**
082 * Set the optional Java class expected by this Descriptor.
083 *
084 * @param type The new expected type
085 */
086 public void setType(Class type);
087
088
089 /**
090 * Return the XPath expression used to access the Java object
091 * referenced by this Descriptor.
092 */
093 public String getXpath();
094
095
096 /**
097 * Set the XPath expression used to access the Java object
098 * referenced by this Descriptor.
099 *
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 }