View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.jxpath;
18  
19  /**
20   * The  {@link JXPathContext#createPath JXPathContext.createPath()} method of
21   * JXPathContext can create missing objects as it traverses an XPath; it
22   * utilizes an AbstractFactory for that purpose. Install a factory on
23   * JXPathContext by calling {@link JXPathContext#setFactory JXPathContext.
24   * setFactory()}.
25   * <p>
26   * All  methods of this class return false.  Override any of them to return true
27   * to indicate that the factory has successfully created the described object.
28   *
29   * @author Dmitri Plotnikov
30   * @version $Revision: 652845 $ $Date: 2008-05-02 13:46:46 -0400 (Fri, 02 May 2008) $
31   */
32  public abstract class AbstractFactory {
33  
34      /**
35       * The  parameters may describe a collection element or an individual
36       * object. It is up to the factory to infer which one it is. If it is a
37       * collection, the factory should check if the collection exists.  If not,
38       * it should create the collection. Then it should create the index'th
39       * element of the collection and return true.
40       * <p>
41       *
42       * @param context can be used to evaluate other XPaths, get to variables
43       * etc.
44       * @param pointer describes the location of the node to be created
45       * @param parent is the object that will serve as a parent of the new
46       * object
47       * @param name is the name of the child of the parent that needs to be
48       * created. In the case of DOM may be qualified.
49       * @param index is used if the pointer represents a collection element. You
50       * may need to expand or even create the collection to accommodate the new
51       * element.
52       *
53       * @return true if the object was successfully created
54       */
55      public boolean createObject(JXPathContext context, Pointer pointer,
56                                  Object parent, String name, int index) {
57          return false;
58      }
59  
60      /**
61       * Declare the specified variable
62       *
63       * @param context hosts variable pools. See
64       * {@link JXPathContext#getVariables() JXPathContext.getVariables()}
65       * @param name is the name of the variable without the "$" sign
66       *
67       * @return true if the variable was successfully defined
68       */
69      public boolean declareVariable(JXPathContext context, String name) {
70          return false;
71      }
72  }