.. java:import:: java.io Serializable

.. java:import:: java.sql CallableStatement

.. java:import:: java.sql Connection

.. java:import:: java.sql PreparedStatement

.. java:import:: java.sql ResultSet

.. java:import:: java.sql SQLException

.. java:import:: java.sql Statement

.. java:import:: java.sql Types

.. java:import:: java.util ArrayList

.. java:import:: java.util Arrays

.. java:import:: java.util HashMap

.. java:import:: java.util HashSet

.. java:import:: java.util Iterator

.. java:import:: java.util LinkedList

.. java:import:: java.util List

.. java:import:: java.util Map

.. java:import:: java.util Map.Entry

.. java:import:: java.util Set

.. java:import:: java.util UUID

.. java:import:: org.antlr.v4.runtime CharStreams

.. java:import:: org.antlr.v4.runtime CommonTokenStream

.. java:import:: org.apache.commons.jcs.access.behavior ICacheAccess

.. java:import:: org.apache.shiro.subject Subject

.. java:import:: org.caosdb.api.entity.v1 MessageCode

.. java:import:: org.caosdb.datetime UTCDateTime

.. java:import:: org.caosdb.server CaosDBServer

.. java:import:: org.caosdb.server ServerProperties

.. java:import:: org.caosdb.server.accessControl Principal

.. java:import:: org.caosdb.server.caching Cache

.. java:import:: org.caosdb.server.database.access Access

.. java:import:: org.caosdb.server.database.backend.implementation MySQL.ConnectionException

.. java:import:: org.caosdb.server.database.backend.implementation MySQL.MySQLHelper

.. java:import:: org.caosdb.server.database.backend.transaction RetrieveFullEntityTransaction

.. java:import:: org.caosdb.server.database.backend.transaction RetrieveSparseEntity

.. java:import:: org.caosdb.server.database.misc DBHelper

.. java:import:: org.caosdb.server.database.misc TransactionBenchmark

.. java:import:: org.caosdb.server.entity Entity

.. java:import:: org.caosdb.server.entity EntityID

.. java:import:: org.caosdb.server.entity EntityInterface

.. java:import:: org.caosdb.server.entity Message

.. java:import:: org.caosdb.server.entity Message.MessageType

.. java:import:: org.caosdb.server.entity RetrieveEntity

.. java:import:: org.caosdb.server.entity.container TransactionContainer

.. java:import:: org.caosdb.server.entity.xml ToElementable

.. java:import:: org.caosdb.server.permissions EntityACL

.. java:import:: org.caosdb.server.permissions EntityPermission

.. java:import:: org.caosdb.server.query CQLParser.CqContext

.. java:import:: org.caosdb.server.query CQLParsingErrorListener.ParsingError

.. java:import:: org.caosdb.server.transaction EntityTransactionInterface

.. java:import:: org.caosdb.server.transaction Retrieve

.. java:import:: org.caosdb.server.transaction Transaction

.. java:import:: org.caosdb.server.transaction WriteTransaction

.. java:import:: org.jdom2 Element

.. java:import:: org.slf4j Logger

Query
=====

.. java:package:: org.caosdb.server.query
   :noindex:

.. java:type:: public class Query implements QueryInterface, ToElementable, EntityTransactionInterface

   This class represents a single, complete Query execution from the parsing of the query string to the resulting list of entity ids.

   This class handles caching of queries and checking retrieve permissions as well. It does not, however, retrieve the resulting entities; this is handled by the \ :java:ref:`Retrieve`\  class.

   :author: Timm Fitschen

Fields
------
resultSet
^^^^^^^^^

.. java:field::  List<IdVersionAclTriplet> resultSet
   :outertype: Query

Constructors
------------
Query
^^^^^

.. java:constructor:: public Query(String query)
   :outertype: Query

Query
^^^^^

.. java:constructor:: public Query(String query, Subject user)
   :outertype: Query

Query
^^^^^

.. java:constructor:: public Query(String query, Transaction<? extends TransactionContainer> transaction)
   :outertype: Query

Query
^^^^^

.. java:constructor:: public Query(String query, Subject user, TransactionContainer container, EntityTransactionInterface transaction, Access access)
   :outertype: Query

Methods
-------
addBenchmark
^^^^^^^^^^^^

.. java:method:: @Override public void addBenchmark(String str, long time)
   :outertype: Query

addToElement
^^^^^^^^^^^^

.. java:method:: @Override public void addToElement(Element parent)
   :outertype: Query

applyQueryTemplates
^^^^^^^^^^^^^^^^^^^

.. java:method:: public void applyQueryTemplates(QueryInterface query, String resultSet) throws QueryException
   :outertype: Query

   Finds all QueryTemplates in the resultSet and applies them to the same resultSet. The IDs of the QueryTemplates themselves are then removed from the resultSet. If the current user doesn't have the RETRIEVE:ENTITY permission for a particular QueryTemplate it will be ignored.

   :param resultSet:
   :throws QueryException:

clearCache
^^^^^^^^^^

.. java:method:: public static void clearCache()
   :outertype: Query

   Remove all cached queries from the cache.

execute
^^^^^^^

.. java:method:: @Override public void execute() throws ParsingException, QueryException
   :outertype: Query

   Execute the query.

   First try the cache and only then use the back-end.

   :throws ParsingException,: QueryException

executeQueryInBackend
^^^^^^^^^^^^^^^^^^^^^

.. java:method:: protected void executeQueryInBackend(Access access) throws SQLException
   :outertype: Query

filterIntermediateResult
^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public void filterIntermediateResult(String tabname) throws SQLException
   :outertype: Query

   Filter out all entities which may not be retrieved by this user due to a missing RETRIEVE permission. This function is also designed for filtering of intermediate results.

   :param tabname:
   :throws SQLException:

getAccess
^^^^^^^^^

.. java:method:: @Override public Access getAccess()
   :outertype: Query

getCacheKey
^^^^^^^^^^^

.. java:method::  String getCacheKey(boolean addUser)
   :outertype: Query

   Return a key for the query cache. The key should describe the query with all the filters but without the FIND, COUNT and SELECT ... FROM parts.

   :return: A Cache key.

getConnection
^^^^^^^^^^^^^

.. java:method:: @Override public Connection getConnection()
   :outertype: Query

getCount
^^^^^^^^

.. java:method:: public int getCount()
   :outertype: Query

getETag
^^^^^^^

.. java:method:: public static String getETag()
   :outertype: Query

   Return the ETag.

   The ETag tags the query cache and is renewed each time the cache is being cleared, i.e. each time the database is being updated.

   :return: The ETag

getEntity
^^^^^^^^^

.. java:method:: public Pattern getEntity()
   :outertype: Query

getQuery
^^^^^^^^

.. java:method:: @Override public Query getQuery()
   :outertype: Query

getRole
^^^^^^^

.. java:method:: public Role getRole()
   :outertype: Query

getSelections
^^^^^^^^^^^^^

.. java:method:: public List<Selection> getSelections()
   :outertype: Query

getSourceSet
^^^^^^^^^^^^

.. java:method:: @Override public String getSourceSet()
   :outertype: Query

getTargetSet
^^^^^^^^^^^^

.. java:method:: @Override public String getTargetSet()
   :outertype: Query

getTargetSetCount
^^^^^^^^^^^^^^^^^

.. java:method:: @Override public int getTargetSetCount()
   :outertype: Query

   :return: the number of entities in the resultset. Might be updated by the filters.

getTimestamp
^^^^^^^^^^^^

.. java:method:: @Override public UTCDateTime getTimestamp()
   :outertype: Query

getTransactionBenchmark
^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: @Override public TransactionBenchmark getTransactionBenchmark()
   :outertype: Query

getType
^^^^^^^

.. java:method:: public Type getType()
   :outertype: Query

getUser
^^^^^^^

.. java:method:: @Override public Subject getUser()
   :outertype: Query

isVersioned
^^^^^^^^^^^

.. java:method:: @Override public boolean isVersioned()
   :outertype: Query

matchIdPattern
^^^^^^^^^^^^^^

.. java:method:: @Override public boolean matchIdPattern(String id)
   :outertype: Query

optimize
^^^^^^^^

.. java:method:: public void optimize()
   :outertype: Query

   Optimize the query after parsing. The optimization is purely based on formal rules.

   Implemented rules:

   ..

   #. FIND * -> FIND ENTITY (which basically prevents to copy the complete entity table just to read out the IDs immediately).

parse
^^^^^

.. java:method:: public void parse(boolean optimize) throws ParsingException
   :outertype: Query

   Parse the query and run optimize() if the parameter `optimize` is true.

   :param optimize: whether to run optimize() immediately.
   :throws ParsingException:

parse
^^^^^

.. java:method:: public void parse() throws ParsingException
   :outertype: Query

   Parse the query and run optimize() immediately.

   :throws ParsingException:

setTargetSetCount
^^^^^^^^^^^^^^^^^

.. java:method:: public void setTargetSetCount(Integer c)
   :outertype: Query

toString
^^^^^^^^

.. java:method:: @Override public String toString()
   :outertype: Query