1 /**
2 * This file Copyright (c) 2008-2011 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.module.rssaggregator.util;
35
36 import java.util.List;
37
38 import javax.jcr.Node;
39
40 /**
41 * Specifies a basic set of Magnolia query operations. Implemented by {@link MagnoliaTemplate}. Not often used directly,
42 * but a useful option to enhance testability, as it can easily be mocked or stubbed.
43 *
44 * @author Rob van der Linden Vooren
45 * @see MagnoliaTemplate
46 */
47 public interface MagnoliaQueryOperations {
48
49 /**
50 * Execute a query for a single or {@code null} result object, for the given query. <p/> This method is useful for
51 * running queries with a known outcome. The query is expected to be a single result query; the returned result will
52 * be directly mapped to the corresponding object type.
53 *
54 * @param repository the repository to execute query against
55 * @param query query to execute
56 * @param language query language (either {@link info.magnolia.cms.core.search.Query#XPATH XPATH} or {@link info.magnolia.cms.core.search.Query#SQL SQL}).
57 * @param type the type of the item to query for
58 * @param mapper the mapper used
59 * @return the result object of the required type, or {@code null} in case of a {@code null} query
60 * @throws IncorrectResultSizeDataAccessException
61 * if the query returns more than one results
62 * @throws DataAccessException if there is any problem executing the query
63 */
64 <T> T queryForObject(String repository, String query, String language, String type, ContentMapper<T> mapper) throws DataAccessException;
65
66 /**
67 * Execute a query for a result list of type T, for the given query. <p/>
68 *
69 * @param repository the repository to execute query against
70 * @param query query to execute
71 * @param language query language (either {@link info.magnolia.cms.core.search.Query#XPATH XPATH} or {@link info.magnolia.cms.core.search.Query#SQL SQL}).
72 * @param type the type of the item to query for
73 * @param mapper the mapper used
74 * @return the result object of the required type, or {@code null} in case of a {@code null} query
75 * @throws DataAccessException if there is any problem executing the query
76 */
77 <T> List<T> queryForList(String repository, String query, String language, String type, ContentMapper<T> mapper) throws DataAccessException;
78
79 /**
80 * Execute an XPath query for a single or {@code null} result object, for the given query. <p/> This method is
81 * useful for running queries with a known outcome. The query is expected to be a single result query; the returned
82 * result will be directly mapped to the corresponding object type.
83 *
84 * @param repository the repository to execute query against
85 * @param query query to execute
86 * @param type the type of the item to query for
87 * @param mapper the mapper used
88 * @return the result object of the required type, or {@code null} in case of a {@code null} query
89 * @throws IncorrectResultSizeDataAccessException
90 * if the query returns more than one results
91 * @throws DataAccessException if there is any problem executing the query
92 */
93 <T> T xpathQueryForObject(String repository, String query, String type, ContentMapper<T> mapper) throws DataAccessException;
94
95 /**
96 * Execute an XPath query for a result list of type T, for the given query.
97 *
98 * @param repository the repository to execute query against
99 * @param query query to execute
100 * @param type the type of the item to query for
101 * @param mapper the mapper used
102 * @return the result object of the required type, or {@code null} in case of a {@code null} Xpath query
103 * @throws DataAccessException if there is any problem executing the query
104 */
105 <T> List<T> xpathQueryForList(String repository, String query, String type, ContentMapper<T> mapper) throws DataAccessException;
106
107 /**
108 * Execute an XPath query for a Content node.
109 *
110 * @param repository the repository to execute query against
111 * @param query query to execute
112 * @param type the type of the item to query for
113 * @return the result Content node, or {@code null} if no such node exists
114 * @throws DataAccessException if there is any problem executing the query
115 */
116 Node xpathQueryForContent(String repository, String query, String type) throws DataAccessException;
117
118 }