001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.rdf.rdf4j;
019
020import java.util.Optional;
021import java.util.stream.Stream;
022
023import org.apache.commons.rdf.api.BlankNodeOrIRI;
024import org.apache.commons.rdf.api.Dataset;
025import org.apache.commons.rdf.api.IRI;
026import org.apache.commons.rdf.api.Quad;
027import org.apache.commons.rdf.api.RDFTerm;
028
029/**
030 * Marker interface for RDF4J implementations of Dataset.
031 *
032 * @see RDF4J#createDataset()
033 * @see RDF4J#asDataset(org.eclipse.rdf4j.repository.Repository, Option...)
034 */
035public interface RDF4JDataset extends Dataset, RDF4JGraphLike<Quad> {
036
037    /**
038     * {@inheritDoc}
039     * <p>
040     * Note that for datasets backed by a repository ({@link #asRepository()} is
041     * present), the stream <strong>must be closed</strong> with
042     * {@link Stream#close()}.
043     * <p>
044     * This can generally achieved using a try-with-resources block, e.g.:
045     *
046     * <pre>
047     * int subjects;
048     * try (Stream&lt;RDF4JQuad&gt; s : graph.stream()) {
049     *   subjects = s.map(RDF4JQuad::getSubject).distinct().count()
050     * }
051     * </pre>
052     */
053    @Override
054    Stream<RDF4JQuad> stream();
055
056    /**
057     * {@inheritDoc}
058     * <p>
059     * Note that for datasets backed by a repository ({@link #asRepository()} is
060     * present), the stream <strong>must be closed</strong> with
061     * {@link Stream#close()}.
062     * <p>
063     * This can generally achieved using a try-with-resources block, e.g.:
064     *
065     * <pre>
066     * int subjects;
067     * try (Stream&lt;RDF4JQuad&gt; s : graph.stream()) {
068     *   subjects = s.map(RDF4JQuad::getSubject).distinct().count()
069     * }
070     * </pre>
071     */
072    @Override
073    Stream<RDF4JQuad> stream(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
074
075    /**
076     * {@inheritDoc}
077     * <p>
078     * Note that for datasets backed by a repository ({@link #asRepository()} is
079     * present), the stream <strong>must be closed</strong> with
080     * {@link Stream#close()}.
081     * <p>
082     * This can generally achieved using a try-with-resources block, e.g.:
083     *
084     * <pre>
085     * int graphs;
086     * try (Stream&lt;BlankNodeOrIRI&gt; s : graph.stream()) {
087     *   graphs = s.count()
088     * }
089     * </pre>
090     */
091    @Override
092    Stream<BlankNodeOrIRI> getGraphNames();
093
094    /**
095     * {@inheritDoc}
096     * <p>
097     * Note that for datasets backed by a repository ({@link #asRepository()} is
098     * present), the iterable <strong>must be closed</strong> with
099     * {@link ClosableIterable#close()}.
100     * <p>
101     * This can generally achieved using a try-with-resources block, e.g.:
102     *
103     * <pre>
104     * try (ClosableIterable&lt;Quad&gt; s : graph.iterate()) {
105     *   for (Quad q : quads) {
106     *       return q; // OK to terminate for-loop early
107     *   }
108     * }
109     * </pre>
110     *
111     * If you don't use a try-with-resources block, the iterator will attempt to
112     * close the ClosableIterable when reaching the end of the iteration.
113     */
114    @Override
115    ClosableIterable<Quad> iterate();
116
117    /**
118     * {@inheritDoc}
119     * <p>
120     * Note that for datasets backed by a repository ({@link #asRepository()} is
121     * present), the iterable <strong>must be closed</strong> with
122     * {@link ClosableIterable#close()}.
123     * <p>
124     * This can generally achieved using a try-with-resources block, e.g.:
125     *
126     * <pre>
127     * try (ClosableIterable&lt;Quad&gt; s : graph.iterate(g,s,p,o)) {
128     *   for (Quad q : quads) {
129     *       return q; // OK to terminate for-loop early
130     *   }
131     * }
132     * </pre>
133     *
134     * If you don't use a try-with-resources block, the iterator will attempt to
135     * close the ClosableIterable when reaching the end of the iteration.
136     */
137    @Override
138    ClosableIterable<Quad> iterate(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate,
139            RDFTerm object);
140
141}