ZorbaXQResultItem.java
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2012 The FLWOR 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 package org.zorbaxquery.api.xqj;
17 
18 import javax.xml.xquery.XQConnection;
19 import javax.xml.xquery.XQException;
20 import org.zorbaxquery.api.Item;
21  /**
22  * This class represents an immutable item object obtained from an XQResultSequence using the getItem method.
23  *
24  * A forward only result sequence does not support calling the getter methods multiple times on the same item. To work around this case, the getItem method can be used to obtain a result item and then getter methods may be called multiple times on this item.
25  *
26  * The ZorbaXQResultItem object is dependent on the connection, expression and the sequence from which it was created and is only valid for the duration of those objects. Thus, if any one of those objects is closed, this ZorbaXQResultItem object will be implicitly closed, and it can no longer be used. Similarly re-executing the expression also implicitly closes the associated result sequences, which in turn implicitly closes this result item.
27  *
28  * An XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call close method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions. Not closing this object implicitly or explicitly might result in serious memory leaks.
29  *
30  * Example -
31  * \code{.java}
32  *
33  * XQPreparedExpression expr = conn.prepareExpression("for $i ..");
34  * XQResultSequence result = expr.executeQuery();
35  *
36  * // posititioned before the first item
37  * while (result.next())
38  * {
39  * ZorbaXQResultItem item = result.getItem();
40  * // perform multiple gets on this item
41  * // get DOM
42  * org.w3.dom.Node node = item.getNode();
43  * // get SAX
44  * item.writeItemToSAX(saxHandler);
45  *
46  * item.close(); // good practice. Item will get implicitly closed
47  * // when the expression, connection or sequence is closed.
48  * }
49  *
50  * result.close(); // explicitly close the result sequence
51  * \endcode
52  **/
53 public class ZorbaXQResultItem extends ZorbaXQItem implements javax.xml.xquery.XQResultItem {
54 
55  private XQConnection connection;
56 
57 
58  public ZorbaXQResultItem(Item item, XQConnection conn) {
59  super(item);
60  connection = conn;
61  }
62 
63  /** \brief Gets the XQuery connection associated with this result item
64  *
65  * @return the connection associated with this result item
66  * @throw XQException - if the result item is in a closed state
67  */
68  @Override
69  public XQConnection getConnection() throws XQException {
70  if (super.isClosed()) {
71  throw new XQException("Object closed");
72  }
73  return connection;
74  }
75 
76 
77 
78 }
blog comments powered by Disqus