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.api;
019
020import java.util.ConcurrentModificationException;
021import java.util.stream.Stream;
022
023/**
024 * A "graph-like" interface that contains {@link TripleLike} statements.
025 * <p>
026 * Extended by {@link Graph} (for {@link Triple}) and {@link Dataset} (for
027 * {@link Quad}).
028 * <p>
029 * Unlike {@link Graph} and {@link Dataset}, this interface can support
030 * generalised {@link TripleLike} or {@link QuadLike} statements, but does not
031 * imply semantics like {@link #size()} or the requirement of mapping
032 * {@link RDFTerm} instances from different implementations.
033 * <p>
034 * As {@link TripleLike} do not have a specific {@link Object#equals(Object)}
035 * semantics, the behaviour of methods like {@link #contains(TripleLike)} and
036 * {@link #remove(TripleLike)} is undefined for arguments that are not object
037 * identical to previously added or returned {@link TripleLike} statements.
038 *
039 * @param <T>
040 *            A {@link TripleLike} type used by the graph methods, typically
041 *            {@link Triple} or {@link Quad}
042 *
043 * @since 0.3.0-incubating
044 * @see Graph
045 * @see Dataset
046 * @see TripleLike
047 */
048public interface GraphLike<T extends TripleLike> {
049
050    /**
051     * Add a statement.
052     *
053     * @param statement
054     *            The TripleLike statement to add
055     */
056    void add(T statement);
057
058    /**
059     * Check if statement is contained.
060     *
061     * @param statement
062     *            The {@link TripleLike} statement to check
063     * @return True if the statement is contained
064     */
065    boolean contains(T statement);
066
067    /**
068     * Add a statement.
069     *
070     * @param statement
071     *            The TripleLike statement to add
072     */
073    void remove(T statement);
074
075    /**
076     * Remove all statements.
077     */
078    void clear();
079
080    /**
081     * Number of statements.
082     *
083     * @return Number of statements
084     */
085    long size();
086
087    /**
088     * Return a Stream of contained statements.
089     *
090     * @return A {@link Stream} of {@link TripleLike} statements.
091     */
092    Stream<? extends T> stream();
093
094    /**
095     * Iterate over contained statements.
096     *
097     * @return An {@link Iterable} of {@link TripleLike} statements.
098     * @throws IllegalStateException
099     *             if the {@link Iterable} has been reused
100     * @throws ConcurrentModificationException
101     *             if a concurrency conflict occurs while the Iterator is
102     *             active.
103     */
104    Iterable<T> iterate() throws ConcurrentModificationException, IllegalStateException;
105
106}