com.day.cq.search.QueryBuilder Maven / Gradle / Ivy
Show all versions of aem-sdk-api Show documentation
/*
* Copyright 1997-2008 Day Management AG
* Barfuesserplatz 6, 4001 Basel, Switzerland
* All Rights Reserved.
*
* This software is the confidential and proprietary information of
* Day Management AG, ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Day.
*/
package com.day.cq.search;
import java.io.IOException;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import com.day.cq.search.eval.PredicateEvaluator;
import com.day.cq.search.facets.Facet;
/**
* QueryBuilder is a service for building {@link Query Queries}
* searching the Java Content Repository and which are easily extensible. The
* individual constraints of a {@link Query} are expressed as {@link PredicateEvaluator
* Predicates}, which are pluggable through OSGi mechanisms, ie. one can easily
* define a new {@link PredicateEvaluator} that maps some higher-level search constraint
* to an explicit JCR XPath expression, can filter the search result for
* constraints that cannot be expressed via XPath and automatically provide
* {@link Facet Facets} based on the search results.
*
*
* This service allows to create queries with several convenience methods, for
* example directly from a request using a fixed convention for the structure of
* request parameters that make up the predicates. In addition, it allows to
* store queries in the repository and load them again.
*
*
Example usages
*
* All examples assume that queryBuilder is available as an OSGi
* SCR reference.
*
*
*
* - From HTTP Form Post Request:
*
* Session session = request.getResourceResolver().adaptTo(Session.class);
* Query query = queryBuilder.createQuery(PredicateGroup.create(request.getParameterMap()), session);
* SearchResult result = query.getResult();
* ...
*
* - From key/value map:
*
* Map map = new HashMap();
* map.put("path", "/content");
* map.put("type", "nt:file");
* Query query = builder.createQuery(PredicateGroup.create(map), session);
* SearchResult result = query.getResult();
* ...
*
* - From predicates:
*
* PredicateGroup group = new PredicateGroup();
* group.add(new Predicate("mypath", "path").set("path", "/content"));
* group.add(new Predicate("mytype", "type").set("type", "nt:file"));
* Query query = builder.createQuery(group, session);
* SearchResult result = query.getResult();
* ...
*
*
*
* @since 5.2
*/
public interface QueryBuilder {
/**
* Creates an "empty" query, ie. a query without any constraints. Use
* {@link Query#getPredicates()} to get the root predicate group in order to
* add predicates via {@link PredicateGroup#add(Predicate)}.
*
* @param session
* the JCR session for the query
* @return a query without any predicates
*/
Query createQuery(Session session);
/**
* Creates a query with the given predicate group as root group.
*
* @param predicates
* a predicate group used as the root group
* @param session
* the JCR session for the query
* @return a query to execute
*/
Query createQuery(PredicateGroup predicates, Session session);
/**
* Loads a saved query from the given repository path. The path can either
* point to a String property or to an nt:file node that
* contains the query as a text file (ie. in the
* jcr:content/jcr:data property). In both cases, the query
* definition is expected as a multi-line string in the java properties file
* format, based on the map reader
* {@link PredicateConverter#createPredicates(java.util.Map)}.
*
*
* To store a query, use
* {@link #storeQuery(Query, String, boolean, Session)}.
*
* @param path
* location of the saved query
* @param session
* the JCR session to access the repository
* @return a query loaded from the repository path, ready to execute, or
* null if the query could not be found
* @throws IOException
* if reading from the binary stream failed
* @throws RepositoryException
* if something went wrong in the repository
*
* @since 5.3
*/
Query loadQuery(String path, Session session) throws RepositoryException, IOException;
/**
* Saves a query at the given repository path. This will either create a
* simple string property or an nt:file containing the query as
* a text file, depending on the 'createFile' flag. In both cases, the query
* definition will be stored as a multi-line string in the java properties
* file format, based on the map created from
* {@link PredicateConverter#createMap(PredicateGroup)}. If the full path to
* that property does not exist yet, it will be created using
* nt:unstructured nodes.
*
*
* To load this query again, use {@link #loadQuery(String, Session)}.
*
* @param query
* the query to save
* @param path
* target location
* @param createFile
* if true, an nt:file will be created
* under that path with the query as file contents; otherwise, if
* the value is false, a simple string property will
* be created at the given location
* @param session
* the JCR session to access the repository
* @throws IOException
* if writing to the binary stream failed
* @throws RepositoryException
* if something went wrong in the repository
*
* @since 5.3
*/
void storeQuery(Query query, String path, boolean createFile, Session session) throws RepositoryException, IOException;
/**
* Invalidates the facet cache, removing all currently
* cached facets and forcing a new facet extraction on
* future queries.
*
* @since 6.0
*/
public void clearFacetCache();
}