View Javadoc

1   /*
2    * $Header$
3    * $Revision: 1168 $
4    * $Date: 2006-07-03 04:58:31 -0700 (Mon, 03 Jul 2006) $
5    *
6    * ====================================================================
7    *
8    * Copyright 2000-2002 bob mcwhirter & James Strachan.
9    * All rights reserved.
10   *
11   * Redistribution and use in source and binary forms, with or without
12   * modification, are permitted provided that the following conditions are
13   * met:
14   * 
15   *   * Redistributions of source code must retain the above copyright
16   *     notice, this list of conditions and the following disclaimer.
17   * 
18   *   * Redistributions in binary form must reproduce the above copyright
19   *     notice, this list of conditions and the following disclaimer in the
20   *     documentation and/or other materials provided with the distribution.
21   * 
22   *   * Neither the name of the Jaxen Project nor the names of its
23   *     contributors may be used to endorse or promote products derived 
24   *     from this software without specific prior written permission.
25   * 
26   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
27   * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28   * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
29   * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
30   * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
31   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
32   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
33   * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
34   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
35   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
36   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37   *
38   * ====================================================================
39   * This software consists of voluntary contributions made by many 
40   * individuals on behalf of the Jaxen Project and was originally 
41   * created by bob mcwhirter <bob@werken.com> and 
42   * James Strachan <jstrachan@apache.org>.  For more information on the 
43   * Jaxen Project, please see <http://www.jaxen.org/>.
44   * 
45   * $Id: VariableContext.java 1168 2006-07-03 11:58:31Z elharo $
46   */
47  
48  
49  package org.jaxen;
50  
51  /** Resolves variable bindings within an XPath expression.
52   *
53   *  <p>
54   *  Variables within an XPath expression are denoted using
55   *  notation such as <code>$varName</code> or 
56   *  <code>$nsPrefix:varName</code>, and may
57   *  refer to a <code>Boolean</code>, <code>Double</code>, <code>String</code>,
58   *  node-set (<code>List</code>) or individual XML node.
59   *  </p>
60   *
61   *  <p>
62   *  When a variable is bound to a node-set, the
63   *  actual Java object returned should be a <code>java.util.List</code>
64   *  containing XML nodes from the object-model (e.g. dom4j, JDOM, DOM, etc.)
65   *  being used with the XPath.
66   *  </p>
67   *
68   *  <p>
69   *  A variable may validly be assigned the <code>null</code> value,
70   *  but an unbound variable (one that this context does not know about)
71   *  should cause an {@link UnresolvableException} to be thrown.
72   *  </p>
73   *  
74   *  <p>
75   *  Implementations of this interface should implement <code>Serializable</code>.
76   *  </p>
77   *
78   *  @see SimpleVariableContext
79   *  @see NamespaceContext
80   *
81   *  @author <a href="mailto:bob@werken.com">bob mcwhirter</a>
82   *  @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
83   */
84  public interface VariableContext
85  {
86      /** An implementation should return the value of an XPath variable
87       *  based on the namespace URI and local name of the variable-reference
88       *  expression.
89       *
90       *  <p>
91       *  It must not use the prefix parameter to select a variable,
92       *  because a prefix could be bound to any namespace; the prefix parameter
93       *  could be used in debugging output or other generated information.
94       *  The prefix may otherwise be ignored.
95       *  </p>
96       *
97       *  @param namespaceURI  the namespace URI to which the prefix parameter
98       *                       is bound in the XPath expression. If the variable
99       *                       reference expression had no prefix, the namespace
100      *                       URI is <code>null</code>.
101      *  @param prefix        the prefix that was used in the variable reference
102      *                       expression; this value is ignored and has no effect
103      *  @param localName     the local name of the variable-reference
104      *                       expression. If there is no prefix, then this is
105      *                       the whole name of the variable.
106      *
107      *  @return  the variable's value (which can be <code>null</code>)
108      *  @throws UnresolvableException  when the variable cannot be resolved
109      */
110     public Object getVariableValue( String namespaceURI,
111                                     String prefix,
112                                     String localName )
113         throws UnresolvableException;
114 }