001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.query;
005:
006: import javax.jcr.*;
007: import javax.jcr.lock.LockException;
008: import javax.jcr.version.VersionException;
009: import javax.jcr.nodetype.ConstraintViolationException;
010:
011: /**
012: * A <code>Query</code> object.
013: *
014: */
015: public interface Query {
016:
017: /**
018: * A string constant representing the XPath query language as defined in JCR 1.0.
019: *
020: * @deprecated As of JCR 2.0, this language is deprecated.
021: */
022: public static final String XPATH = "xpath";
023:
024: /**
025: * A string constant representing the SQL query language as defined in JCR 1.0.
026: *
027: * @deprecated As of JCR 2.0, this language is deprecated.
028: */
029: public static final String SQL = "sql";
030:
031: /**
032: * A string constant representing the JCR-SQL2 query language.
033: *
034: * @since JCR 2.0
035: */
036: public static final String JCR_SQL2 = "JCR-SQL2";
037:
038: /**
039: * A string constant representing the JCR-JQOM query language.
040: *
041: * @since JCR 2.0
042: */
043: public static final String JCR_JQOM = "JCR-JQOM";
044:
045: /**
046: * Flag determining the scope of a query. For details, see {@link #execute(int)}.
047: * @since JCR 2.0
048: */
049: public static final int SEARCH_WORKSPACE = 1;
050:
051: /**
052: * Flag determining the scope of a query. For details, see {@link #execute(int)}.
053: * @since JCR 2.0
054: */
055: public static final int SEARCH_WORKSPACE_NO_SYSTEM = 2;
056:
057: /**
058: * Flag determining the scope of a query. For details, see {@link #execute(int)}.
059: * @since JCR 2.0
060: */
061: public static final int SEARCH_VERSIONS = 3;
062:
063: /**
064: * Executes this query and returns a <code>{@link QueryResult}</code> object.
065: * <p/>
066: * Equivalent to <code>execute(SEARCH_CURRENT_WORKSPACE)</code>.
067: *
068: * @return a <code>QueryResult</code> object
069: * @throws RepositoryException if an error occurs
070: */
071: public QueryResult execute() throws RepositoryException;
072:
073: /**
074: * Executes this query and returns a <code>{@link QueryResult}</code>.
075: * <p/>
076: * The flag <code>searchSpace</code> determines the scope of the search:
077: * <p/>
078: * <code>SEARCH_WORKSPACE</code>: Search the current workspace. In
079: * repositories that support full versioning, each workspace includes a
080: * subtree <code>/jcr:system/jcr:versionStorage</code> which reflects the
081: * version information of the repository. In such repositories this option
082: * will search the entire workspace including this version storage subtree.
083: * <p/>
084: * In repositories that support only simple versioning, repository version
085: * storage is <i>not</i> reflected in workspace content and so this option
086: * will, by definition, not search versions. In that case searching of
087: * versions can be done with the <code>SEARCH_VERSIONS</code> option.
088: * <p/>
089: * In either of the above cases, if a repository supports other features
090: * that mandate the storage of data under <code>/jcr:system</code> these
091: * substructures will be searched under this option. To prevent search of
092: * the system node subtree the option <code>SEARCH_WORKSPACE_NO_SYSTEM</code>
093: * can be used.
094: * <p/>
095: * This option is equivalent to the zero-parameter signature {@link #execute()}.
096: * <p/>
097: * <code>SEARCH_WORKSPACE_NO_SYSTEM</code>: Searches the current workspace
098: * except for the <code>/jcr:system</code> subtree. If no <code>/jcr:system</code>
099: * subtree exists this option is equivalent to <code>SEARCH_WORKSPACE</code>.
100: * <p/>
101: * <code>SEARCH_VERSIONS</code>: Search all versions of all nodes in the
102: * repository. This option will search version storage regardless of whether
103: * it is reflected in workspace content (as when full versioning is s
104: * upported) or hidden within the implementation (as when only simple
105: * versioning is supported). Queries using this option will return results
106: * in the form of <code>nt:version</code> nodes even in repositories that do
107: * not expose version storage as content in the the workspace.
108: * <p/>
109: * In repositories that support only simple versioning, using this option is
110: * the only way to search version information. In repositories that support
111: * full versioning this option is also supported though queries involving
112: * features unique to full versioning will still require direct search of
113: * the version history structure below <code>/jcr:system/jcr:versionHistory</code>.
114: * <p/>
115: * A <code>SearchNotSupportedException</code> is thrown if the <code>QueryManager</code>
116: * does not support the search mode.
117: * <p/>
118: * Throws a <code>RepositoryException</code> if an error occurs.
119: *
120: * @param searchSpace flag which determines the scope of the search
121: * @return a <code>QueryResult</code>
122: * @throws SearchNotSupportedException if the <code>QueryManager</code>
123: * does not support the search mode.
124: * @throws RepositoryException if an error occurs
125: * @since JCR 2.0
126: */
127: public QueryResult execute(int searchSpace)
128: throws SearchNotSupportedException, RepositoryException;
129:
130: /**
131: * Sets the maximum size of the result set to <code>limit</code>.
132: *
133: * @param limit a <code>long</code>
134: * @since JCR 2.0
135: */
136: public void setLimit(long limit);
137:
138: /**
139: * Sets the start offset of the result set to <code>offset</code>.
140: *
141: * @param offset a <code>long</code>
142: * @since JCR 2.0
143: */
144: public void setOffset(long offset);
145:
146: /**
147: * Returns the statement defined for this query.
148: * <p/>
149: * If the language of this query is string-based (like JCR-SQL2), this
150: * method will return the statement that was used to create this query.
151: * <p/>
152: * If the language of this query is JCR-JQOM, this method will return the
153: * JCR-SQL2 equivalent of the JCR-JQOM object tree.
154: * <p/>
155: * This is the standard serialization of JCR-JQOM and is also the string
156: * stored in the <code>jcr:statement</code> property if the query is
157: * persisted. See {@link #storeAsNode(String)}.
158: *
159: * @return the query statement.
160: */
161: public String getStatement();
162:
163: /**
164: * Returns the language set for this query. This will be one of the
165: * query language constants returned by
166: * {@link QueryManager#getSupportedQueryLanguages}.
167: *
168: * @return the query language.
169: */
170: public String getLanguage();
171:
172: /**
173: * If this is a <code>Query</code> object that has been stored using
174: * {@link Query#storeAsNode} (regardless of whether it has been <code>save</code>d yet)
175: * or retrieved using {@link QueryManager#getQuery}), then this method
176: * returns the path of the <code>nt:query</code> node that stores the query.
177: * If this is a transient query (that is, a <code>Query</code> object created with
178: * {@link QueryManager#createQuery} but not yet stored), then this method throws an
179: * <code>ItemNotFoundException</code>.
180: *
181: * @return path of the node representing this query.
182: * @throws ItemNotFoundException if this query is not a stored query.
183: * @throws RepositoryException if another error occurs.
184: */
185: public String getStoredQueryPath() throws ItemNotFoundException,
186: RepositoryException;
187:
188: /**
189: * Creates a node representing this <code>Query</code> in content.
190: * <p/>
191: * In a level 1 repository this method throws an <code>UnsupportedRepositoryOperationException</code>.
192: * <p/>
193: * In a level 2 repository it creates a node of type <code>nt:query</code> at <code>absPath</code>
194: * and returns that node.
195: * <p/>
196: * In order to persist the newly created node, a <code>save</code> must be performed that includes <i>the
197: * parent</i> of this new node within its scope. In other words, either a <code>Session.save</code> or
198: * an <code>Item.save</code> on the parent or higher-degree ancestor of <code>absPath</code> must be performed.
199: * <p/>
200: * In the context of this method the <code>absPath</code> provided must not
201: * have an index on its final element. If it does then a <code>RepositoryException</code>
202: * is thrown.
203: * <p/>
204: * Strictly speaking, the parameter is actually a absolute path to the parent
205: * node of the node to be added, appended with the name desired for the new
206: * node. It does not specify a position within the child node ordering (if
207: * such ordering is supported). If ordering is supported by the node type
208: * of the parent node then the new node is appended to the end of the child
209: * node list.
210: * <p/>
211: * An <code>ItemExistsException</code> will be thrown either immediately (by
212: * this method), or on <code>save</code>, if an item at the specified path already exists
213: * and same-name siblings are not allowed. Implementations may differ on
214: * when this validation is performed.
215: * <p/>
216: * A <code>PathNotFoundException</code> will be thrown either immediately,
217: * or on <code>save</code>, if the specified path implies intermediary
218: * nodes that do not exist. Implementations may differ on when this validation is performed.
219: * <p/>
220: * A <code>ConstraintViolationException</code>will be thrown either immediately
221: * or on <code>save</code>, if adding the node would violate a node type or implementation-specific
222: * constraint or if an attempt is made to add a node as the child of a property.
223: * Implementations may differ on when this validation is performed.
224: * <p/>
225: * A <code>VersionException</code> will be thrown either immediately (by
226: * this method), or on <code>save</code>, if the node to which the new child is being
227: * added is versionable and checked-in or is non-versionable but its nearest
228: * versionable ancestor is checked-in. Implementations may differ on when
229: * this validation is performed.
230: * <p/>
231: * A <code>LockException</code> will be thrown either immediately (by
232: * this method), or on <code>save</code>, if a lock prevents the addition of the node.
233: * Implementations may differ on when this validation is performed.
234: *
235: * @param absPath absolute path the query should be stored at
236: * @return the newly created node.
237: *
238: * @throws ItemExistsException if an item at the specified path already exists,
239: * same-name siblings are not allowed and this implementation performs this
240: * validation immediately instead of waiting until <code>save</code>.
241: *
242: * @throws PathNotFoundException if the specified path implies intermediary
243: * <code>Node</code>s that do not exist or the last element of
244: * <code>relPath</code> has an index, and this implementation performs this
245: * validation immediately instead of waiting until <code>save</code>.
246: *
247: * @throws ConstraintViolationException if a node type or implementation-specific constraint
248: * is violated or if an attempt is made to add a node as the child of a property and this
249: * implementation performs this validation immediately instead of waiting until <code>save</code>.
250: *
251: * @throws VersionException if the node to which the new child is being added is versionable and
252: * checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this
253: * implementation performs this validation immediately instead of waiting until <code>save</code>.
254: *
255: * @throws LockException if a lock prevents the addition of the node and this
256: * implementation performs this validation immediately instead of waiting until <code>save</code>.
257: *
258: * @throws UnsupportedRepositoryOperationException in a level 1 implementation.
259: *
260: * @throws RepositoryException if another error occurs or if the <code>absPath</code> provided has
261: * an index on its final element.
262: */
263: public Node storeAsNode(String absPath) throws ItemExistsException,
264: PathNotFoundException, VersionException,
265: ConstraintViolationException, LockException,
266: UnsupportedRepositoryOperationException,
267: RepositoryException;
268: }
|