1 /** 2 * This file Copyright (c) 2003-2014 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 * @version $Id$ 51 * 52 * @deprecated Since 4.5.4 we are using JCR query API. 53 */ 54 55 public interface Query { 56 57 String XPATH = "xpath"; 58 59 String SQL = "sql"; 60 61 /** 62 * <i>Description inherited from javax.jcr.query.Query#execute()</i><br> 63 * Executes this query and returns a <code>{@link QueryResult}</code>. 64 * @return a <code>QueryResult</code> 65 * @throws RepositoryException if an error occurs 66 */ 67 QueryResult execute() throws RepositoryException; 68 69 /** 70 * Restrict the result size of subsequent {@link #execute()} invocations to the given 71 * number of objects.<p> 72 * Use this method if the query result can be large, but you are interested 73 * only in the first few objects. This will avoid the rest of the result objects 74 * to be instantiated, resulting in a huge performance gain for large 75 * results and small limit numbers.<p> 76 * The performance gain may be defeated if your query returns a lot of nodes 77 * of the "wrong" nodetype, resulting in {@link QueryResult#getContent(String)} to 78 * iterate often before the limit is reached. So make sure your query yields only nodes with the 79 * required nodetype. 80 * @param limit the maximum result size, initial value is {@link Long#MAX_VALUE} 81 */ 82 void setLimit(long limit); 83 84 /** 85 * <i>Description inherited from javax.jcr.query.Query#getStatement()</i><br> 86 * Returns the statement set for this query. 87 * @return the query statement. 88 */ 89 String getStatement(); 90 91 /** 92 * <i>Description inherited from javax.jcr.query.Query#getLanguage()</i><br> 93 * Returns the language set for this query. This will be one of the query language constants returned by 94 * {@link QueryManager#getSupportedQueryLanguages}. 95 * @return the query language. 96 */ 97 String getLanguage(); 98 99 /** 100 * <i>Description inherited from javax.jcr.query.Query#getStoredQueryPath()</i><br> 101 * If this is a <code>Query</code> object that has been stored using {@link Query#storeAsNode} (regardless of 102 * whether it has been <code>save</code>d yet) or retrieved using {@link QueryManager#getQuery}), then this 103 * method returns the path of the <code>nt:query</code> node that stores the query. If this is a transient query 104 * (that is, a <code>Query</code> object created with {@link QueryManager#createQuery} but not yet stored) then 105 * this method throws an <code>ItemNotFoundException</code>. 106 * @return path of the node representing this query. 107 * @throws ItemNotFoundException if this query is not a stored query. 108 * @throws RepositoryException if another error occurs. 109 */ 110 String getStoredQueryPath() throws ItemNotFoundException, RepositoryException; 111 112 /** 113 * <i>Description inherited from javax.jcr.query.Query#storeAsNode()</i><br> 114 * Creates a node representing this <code>Query</code> in content. <p/> In a level 1 repository this method throws 115 * an <code>UnsupportedRepositoryOperationException</code>. <p/> In a level 2 repository it creates a node of 116 * type <code>nt:query</code> at <code>absPath</code> and returns that node. <p/> In order to persist the newly 117 * created node, a <code>save</code> must be performed that includes <i>the parent</i> of this new node within 118 * its scope. In other words, either a <code>Session.save</code> or an <code>Item.save</code> on the parent or 119 * higher-degree ancestor of <code>absPath</code> must be performed. <p/> An <code>ItemExistsException</code> 120 * will be thrown either immediately (by this method), or on <code>save</code>, if an item at the specified path 121 * already exists and same-name siblings are not allowed. Implementations may differ on when this validation is 122 * performed. <p/> A <code>PathNotFoundException</code> will be thrown either immediately , or on 123 * <code>save</code>, if the specified path implies intermediary nodes that do not exist. Implementations may 124 * differ on when this validation is performed. <p/> A <code>ConstraintViolationException</code>will be thrown 125 * either immediately or on <code>save</code>, if adding the node would violate a node type or 126 * implementation-specific constraintor if an attempt is made to add a node as the child of a property. 127 * Implementations may differ on when this validation is performed. <p/> A <code>VersionException</code> will be 128 * thrown either immediately (by this method), or on <code>save</code>, if the node to which the new child is 129 * being added is versionable and checked-in or is non-versionable but its nearest versionable ancestor is 130 * checked-in. Implementations may differ on when this validation is performed. <p/> A <code>LockException</code> 131 * will be thrown either immediately (by this method), or on <code>save</code>, if a lock prevents the addition 132 * of the node. Implementations may differ on when this validation is performed. 133 * @return the newly created node. 134 * @throws ItemExistsException if an item at the specified path already exists, same-name siblings are not allowed 135 * and this implementation performs this validation immediately instead of waiting until <code>save</code>. 136 * @throws PathNotFoundException if the specified path implies intermediary <code>Node</code>s that do not exist 137 * or the last element of <code>relPath</code> has an index, and this implementation performs this validation 138 * immediately instead of waiting until <code>save</code>. 139 * @throws ConstraintViolationException if a node type or implementation-specific constraint is violated or if an 140 * attempt is made to add a node as the child of a property and this implementation performs this validation 141 * immediately instead of waiting until <code>save</code>. 142 * @throws VersionException if the node to which the new child is being added is versionable and checked-in or is 143 * non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this 144 * validation immediately instead of waiting until <code>save</code>. 145 * @throws LockException if a lock prevents the addition of the node and this implementation performs this 146 * validation immediately instead of waiting until <code>save</code>. 147 * @throws UnsupportedRepositoryOperationException in a level 1 implementation. 148 * @throws RepositoryException if another error occurs or if the <code>relPath</code> provided has an index on its 149 * final element. 150 */ 151 Node storeAsNode(String s) throws ItemExistsException, PathNotFoundException, VersionException, 152 ConstraintViolationException, LockException, UnsupportedRepositoryOperationException, RepositoryException; 153 154 }