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    }