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;
028import org.apache.commons.rdf.rdf4j.RDF4J.Option;
029
030/**
031 * Marker interface for RDF4J implementations of Dataset.
032 *
033 * @see RDF4J#createDataset()
034 * @see RDF4J#asDataset(org.eclipse.rdf4j.repository.Repository, Option...)
035 */
036public interface RDF4JDataset extends Dataset, RDF4JGraphLike<Quad> {
037
038    /**
039     * {@inheritDoc}
040     * <p>
041     * Note that for datasets backed by a repository ({@link #asRepository()} is
042     * present), the stream <strong>must be closed</strong> with
043     * {@link Stream#close()}.
044     * <p>
045     * This can generally achieved using a try-with-resources block, e.g.:
046     *
047     * <pre>
048     * int subjects;
049     * try (Stream&lt;RDF4JQuad&gt; s : graph.stream()) {
050     *   subjects = s.map(RDF4JQuad::getSubject).distinct().count()
051     * }
052     * </pre>
053     */
054    @Override
055    Stream<RDF4JQuad> stream();
056
057    /**
058     * {@inheritDoc}
059     * <p>
060     * Note that for datasets backed by a repository ({@link #asRepository()} is
061     * present), the stream <strong>must be closed</strong> with
062     * {@link Stream#close()}.
063     * <p>
064     * This can generally achieved using a try-with-resources block, e.g.:
065     *
066     * <pre>
067     * int subjects;
068     * try (Stream&lt;RDF4JQuad&gt; s : graph.stream()) {
069     *   subjects = s.map(RDF4JQuad::getSubject).distinct().count()
070     * }
071     * </pre>
072     */
073    @Override
074    Stream<RDF4JQuad> stream(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
075
076    /**
077     * {@inheritDoc}
078     * <p>
079     * Note that for datasets backed by a repository ({@link #asRepository()} is
080     * present), the stream <strong>must be closed</strong> with
081     * {@link Stream#close()}.
082     * <p>
083     * This can generally achieved using a try-with-resources block, e.g.:
084     *
085     * <pre>
086     * int graphs;
087     * try (Stream&lt;BlankNodeOrIRI&gt; s : graph.stream()) {
088     *   graphs = s.count()
089     * }
090     * </pre>
091     */
092    @Override
093    Stream<BlankNodeOrIRI> getGraphNames();
094
095    /**
096     * {@inheritDoc}
097     * <p>
098     * Note that for datasets backed by a repository ({@link #asRepository()} is
099     * present), the iterable <strong>must be closed</strong> with
100     * {@link ClosableIterable#close()}.
101     * <p>
102     * This can generally achieved using a try-with-resources block, e.g.:
103     *
104     * <pre>
105     * try (ClosableIterable&lt;Quad&gt; s : graph.iterate()) {
106     *   for (Quad q : quads) {
107     *       return q; // OK to terminate for-loop early
108     *   }
109     * }
110     * </pre>
111     *
112     * If you don't use a try-with-resources block, the iterator will attempt to
113     * close the ClosableIterable when reaching the end of the iteration.
114     */
115    @Override
116    ClosableIterable<Quad> iterate();
117
118    /**
119     * {@inheritDoc}
120     * <p>
121     * Note that for datasets backed by a repository ({@link #asRepository()} is
122     * present), the iterable <strong>must be closed</strong> with
123     * {@link ClosableIterable#close()}.
124     * <p>
125     * This can generally achieved using a try-with-resources block, e.g.:
126     *
127     * <pre>
128     * try (ClosableIterable&lt;Quad&gt; s : graph.iterate(g,s,p,o)) {
129     *   for (Quad q : quads) {
130     *       return q; // OK to terminate for-loop early
131     *   }
132     * }
133     * </pre>
134     *
135     * If you don't use a try-with-resources block, the iterator will attempt to
136     * close the ClosableIterable when reaching the end of the iteration.
137     */
138    @Override
139    ClosableIterable<Quad> iterate(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate,
140            RDFTerm object);
141
142}