1 /**
2 * This file Copyright (c) 2003-2010 Magnolia International
3 * Ltd. (http://www.magnolia-cms.com). All rights reserved.
4 *
5 *
6 * This file is dual-licensed under both the Magnolia
7 * Network Agreement and the GNU General Public License.
8 * You may elect to use one or the other of these licenses.
9 *
10 * This file is distributed in the hope that it will be
11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
12 * implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
14 * Redistribution, except as permitted by whichever of the GPL
15 * or MNA you select, is prohibited.
16 *
17 * 1. For the GPL license (GPL), you can redistribute and/or
18 * modify this file under the terms of the GNU General
19 * Public License, Version 3, as published by the Free Software
20 * Foundation. You should have received a copy of the GNU
21 * General Public License, Version 3 along with this program;
22 * if not, write to the Free Software Foundation, Inc., 51
23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
24 *
25 * 2. For the Magnolia Network Agreement (MNA), this file
26 * and the accompanying materials are made available under the
27 * terms of the MNA which accompanies this distribution, and
28 * is available at http://www.magnolia-cms.com/mna.html
29 *
30 * Any modifications to this file must keep this entire header
31 * intact.
32 *
33 */
34 package info.magnolia.cms.core.search;
35
36 import javax.jcr.ItemExistsException;
37 import javax.jcr.ItemNotFoundException;
38 import javax.jcr.Node;
39 import javax.jcr.PathNotFoundException;
40 import javax.jcr.RepositoryException;
41 import javax.jcr.UnsupportedRepositoryOperationException;
42 import javax.jcr.lock.LockException;
43 import javax.jcr.nodetype.ConstraintViolationException;
44 import javax.jcr.version.VersionException;
45
46
47 /**
48 * Equivalent to {@link javax.jcr.query.Query} but working with {@link Content} objects.
49 * Date: Apr 4, 2005 Time: 11:02:35 AM
50 * @author Sameer Charles
51 */
52
53 public interface Query {
54
55 String XPATH = "xpath"; //$NON-NLS-1$
56
57 String SQL = "sql"; //$NON-NLS-1$
58
59 /**
60 * <i>Description inherited from javax.jcr.query.Query#execute()</i><br>
61 * Executes this query and returns a <code>{@link QueryResult}</code>.
62 * @return a <code>QueryResult</code>
63 * @throws RepositoryException if an error occurs
64 */
65 QueryResult execute() throws RepositoryException;
66
67 /**
68 * <i>Description inherited from javax.jcr.query.Query#getStatement()</i><br>
69 * Returns the statement set for this query.
70 * @return the query statement.
71 */
72 String getStatement();
73
74 /**
75 * <i>Description inherited from javax.jcr.query.Query#getLanguage()</i><br>
76 * Returns the language set for this query. This will be one of the query language constants returned by
77 * {@link QueryManager#getSupportedQueryLanguages}.
78 * @return the query language.
79 */
80 String getLanguage();
81
82 /**
83 * <i>Description inherited from javax.jcr.query.Query#getStoredQueryPath()</i><br>
84 * If this is a <code>Query</code> object that has been stored using {@link Query#storeAsNode} (regardless of
85 * whether it has been <code>save</code>d yet) or retrieved using {@link QueryManager#getQuery}), then this
86 * method returns the path of the <code>nt:query</code> node that stores the query. If this is a transient query
87 * (that is, a <code>Query</code> object created with {@link QueryManager#createQuery} but not yet stored) then
88 * this method throws an <code>ItemNotFoundException</code>.
89 * @return path of the node representing this query.
90 * @throws ItemNotFoundException if this query is not a stored query.
91 * @throws RepositoryException if another error occurs.
92 */
93 String getStoredQueryPath() throws ItemNotFoundException, RepositoryException;
94
95 /**
96 * <i>Description inherited from javax.jcr.query.Query#storeAsNode()</i><br>
97 * Creates a node representing this <code>Query</code> in content. <p/> In a level 1 repository this method throws
98 * an <code>UnsupportedRepositoryOperationException</code>. <p/> In a level 2 repository it creates a node of
99 * type <code>nt:query</code> at <code>absPath</code> and returns that node. <p/> In order to persist the newly
100 * created node, a <code>save</code> must be performed that includes <i>the parent</i> of this new node within
101 * its scope. In other words, either a <code>Session.save</code> or an <code>Item.save</code> on the parent or
102 * higher-degree ancestor of <code>absPath</code> must be performed. <p/> An <code>ItemExistsException</code>
103 * will be thrown either immediately (by this method), or on <code>save</code>, if an item at the specified path
104 * already exists and same-name siblings are not allowed. Implementations may differ on when this validation is
105 * performed. <p/> A <code>PathNotFoundException</code> will be thrown either immediately , or on
106 * <code>save</code>, if the specified path implies intermediary nodes that do not exist. Implementations may
107 * differ on when this validation is performed. <p/> A <code>ConstraintViolationException</code>will be thrown
108 * either immediately or on <code>save</code>, if adding the node would violate a node type or
109 * implementation-specific constraintor if an attempt is made to add a node as the child of a property.
110 * Implementations may differ on when this validation is performed. <p/> A <code>VersionException</code> will be
111 * thrown either immediately (by this method), or on <code>save</code>, if the node to which the new child is
112 * being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
113 * checked-in. Implementations may differ on when this validation is performed. <p/> A <code>LockException</code>
114 * will be thrown either immediately (by this method), or on <code>save</code>, if a lock prevents the addition
115 * of the node. Implementations may differ on when this validation is performed.
116 * @return the newly created node.
117 * @throws ItemExistsException if an item at the specified path already exists, same-name siblings are not allowed
118 * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
119 * @throws PathNotFoundException if the specified path implies intermediary <code>Node</code>s that do not exist
120 * or the last element of <code>relPath</code> has an index, and this implementation performs this validation
121 * immediately instead of waiting until <code>save</code>.
122 * @throws ConstraintViolationException if a node type or implementation-specific constraint is violated or if an
123 * attempt is made to add a node as the child of a property and this implementation performs this validation
124 * immediately instead of waiting until <code>save</code>.
125 * @throws VersionException if the node to which the new child is being added is versionable and checked-in or is
126 * non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this
127 * validation immediately instead of waiting until <code>save</code>.
128 * @throws LockException if a lock prevents the addition of the node and this implementation performs this
129 * validation immediately instead of waiting until <code>save</code>.
130 * @throws UnsupportedRepositoryOperationException in a level 1 implementation.
131 * @throws RepositoryException if another error occurs or if the <code>relPath</code> provided has an index on its
132 * final element.
133 */
134 Node storeAsNode(String s) throws ItemExistsException, PathNotFoundException, VersionException,
135 ConstraintViolationException, LockException, UnsupportedRepositoryOperationException, RepositoryException;
136
137 }