001: /*
002: * Copyright Aduna (http://www.aduna-software.com/) (c) 2007.
003: *
004: * Licensed under the Aduna BSD-style license.
005: */
006: package org.openrdf.repository;
007:
008: import java.util.ArrayList;
009: import java.util.Collection;
010: import java.util.List;
011:
012: import info.aduna.iteration.CloseableIteration;
013: import info.aduna.iteration.DistinctIteration;
014: import info.aduna.iteration.IterationWrapper;
015:
016: /**
017: * A RepositoryResult is a result collection of objects (for example
018: * {@link org.openrdf.model.Statement}, {@link org.openrdf.model.Namespace},
019: * or {@link org.openrdf.model.Resource} objects) that can be iterated over. It
020: * keeps an open connection to the backend for lazy retrieval of individual
021: * results. Additionally it has some utility methods to fetch all results and
022: * add them to a collection.
023: * <p>
024: * By default, a RepositoryResult is not necessarily a (mathematical) set: it
025: * may contain duplicate objects. Duplicate filtering can be {{@link #enableDuplicateFilter() switched on},
026: * but this should not be used lightly as the filtering mechanism is potentially
027: * memory-intensive.
028: * <p>
029: * A RepositoryResult needs to be {@link #close() closed} after use to free up
030: * any resources (open connections, read locks, etc.) it has on the underlying
031: * repository.
032: *
033: * @see RepositoryConnection#getStatements(org.openrdf.model.Resource,
034: * org.openrdf.model.URI, org.openrdf.model.Value, boolean,
035: * org.openrdf.model.Resource[])
036: * @see RepositoryConnection#getNamespaces()
037: * @see RepositoryConnection#getContextIDs()
038: * @author jeen
039: * @author Arjohn Kampman
040: */
041: public class RepositoryResult<T> extends
042: IterationWrapper<T, RepositoryException> {
043:
044: public RepositoryResult(
045: CloseableIteration<? extends T, RepositoryException> iter) {
046: super (iter);
047: }
048:
049: /**
050: * Switches on duplicate filtering while iterating over objects. The
051: * RepositoryResult will keep track of the previously returned objects in a
052: * {@link java.util.Set} and on calling next() or hasNext() will ignore any
053: * objects that already occur in this Set.
054: * <P>
055: * Caution: use of this filtering mechanism is potentially memory-intensive.
056: *
057: * @throws RepositoryException
058: * if a problem occurred during initialization of the filter.
059: */
060: public void enableDuplicateFilter() throws RepositoryException {
061: wrappedIter = new DistinctIteration<T, RepositoryException>(
062: wrappedIter);
063: }
064:
065: /**
066: * Returns a {@link List} containing all objects of this RepositoryResult in
067: * order of iteration. The RepositoryResult is fully consumed and
068: * automatically closed by this operation.
069: * <P>
070: * Note: use this method with caution! It pulls the entire RepositoryResult
071: * in memory and as such is potentially very memory-intensive.
072: *
073: * @return a List containing all objects of this RepositoryResult.
074: * @throws RepositoryException
075: * if a problem occurred during retrieval of the results.
076: * @see #addTo(Collection)
077: */
078: public List<T> asList() throws RepositoryException {
079: return addTo(new ArrayList<T>());
080: }
081:
082: /**
083: * Adds all objects of this RepositoryResult to the supplied collection. The
084: * RepositoryResult is fully consumed and automatically closed by this
085: * operation.
086: *
087: * @return A reference to the collection that was supplied.
088: * @throws RepositoryException
089: * if a problem occurred during retrieval of the results.
090: */
091: public <C extends Collection<T>> C addTo(C collection)
092: throws RepositoryException {
093: try {
094: while (hasNext()) {
095: collection.add(next());
096: }
097:
098: return collection;
099: } finally {
100: close();
101: }
102: }
103: }
|