/*****************************************************************
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
****************************************************************/
package org.apache.cayenne.query;
import org.apache.cayenne.ObjectContext;
import org.apache.cayenne.ResultBatchIterator;
import org.apache.cayenne.ResultIterator;
import org.apache.cayenne.ResultIteratorCallback;
import java.util.List;
/**
* A common interface for grouping together different kinds of queries that
* return results.
*/
public interface Select<T> extends Query {
/**
* Selects objects using provided context.
* <p>
* Essentially the inversion of "ObjectContext.select(Select)".
*
* @since 4.0
*/
List<T> select(ObjectContext context);
/**
* Selects a single object using provided context. The query is expected to
* match zero or one object. It returns null if no objects were matched. If
* query matched more than one object,
* {@link org.apache.cayenne.CayenneRuntimeException} is thrown.
* <p>
* Essentially the inversion of "ObjectContext.selectOne(Select)".
*
* @since 4.0
*/
T selectOne(ObjectContext context);
/**
* Selects a single object using provided context. The query itself can
* match any number of objects, but will return only the first one. It
* returns null if no objects were matched.
* <p>
* If it matched more than one object, the first object from the list is
* returned. This makes 'selectFirst' different from
* {@link #selectOne(ObjectContext)}, which would throw in this situation.
* 'selectFirst' is useful e.g. when the query is ordered and we only want
* to see the first object (e.g. "most recent news article"), etc.
* <p>
* Selecting the first object via "Select.selectFirst(ObjectContext)" is
* more comprehensible than selecting via
* "ObjectContext.selectFirst(Select)", because implementations of "Select"
* set fetch size limit to one.
*
* @since 4.0
*/
T selectFirst(ObjectContext context);
/**
* Creates a ResultIterator based on the provided context and passes it to a
* callback for processing. The caller does not need to worry about closing
* the iterator. This method takes care of it.
* <p>
* Essentially the inversion of
* "ObjectContext.iterate(Select, ResultIteratorCallback)".
*
* @since 4.0
*/
void iterate(ObjectContext context, ResultIteratorCallback<T> callback);
/**
* Creates a ResultIterator based on the provided context. It is usually
* backed by an open result set and is useful for processing of large data
* sets, preserving a constant memory footprint. The caller must wrap
* iteration in try/finally (or try-with-resources for Java 1.7 and higher)
* and close the ResultIterator explicitly. Or use
* {@link #iterate(ObjectContext, ResultIteratorCallback)} as an
* alternative.
* <p>
* Essentially the inversion of "ObjectContext.iterator(Select)".
*
* @since 4.0
*/
ResultIterator<T> iterator(ObjectContext context);
/**
* Creates a ResultBatchIterator based on the provided context and batch
* size. It is usually backed by an open result set and is useful for
* processing of large data sets, preserving a constant memory footprint.
* The caller must wrap iteration in try/finally (or try-with-resources for
* Java 1.7 and higher) and close the ResultBatchIterator explicitly.
*
* @since 4.0
*/
ResultBatchIterator<T> batchIterator(ObjectContext context, int size);
}