001/*
002 * The contents of this file are subject to the license and copyright
003 * detailed in the LICENSE and NOTICE files at the root of the source
004 * tree.
005 */
006package org.fcrepo.kernel.api;
007
008import org.fcrepo.kernel.api.identifiers.FedoraId;
009import javax.annotation.Nonnull;
010
011import java.time.Instant;
012import java.util.stream.Stream;
013
014/**
015 * An interface for retrieving resource IDs by their containment relationships.
016 *
017 * @author dbernstein
018 * @since 6.0.0
019 */
020public interface ContainmentIndex {
021
022    /**
023     * Return a stream of fedora identifiers contained by the specified fedora resource for the current state of the
024     * repository.
025     *
026     * @param tx The transaction, or null if no transaction
027     * @param fedoraId The ID of the containing fedora resource
028     * @return A stream of contained identifiers
029     */
030    Stream<String> getContains(Transaction tx, FedoraId fedoraId);
031
032    /**
033     * Return a stream of fedora identifiers contained by the specified fedora resource that have deleted
034     * relationships.
035     *
036     * @param tx The transaction, or null if no transaction
037     * @param fedoraId The ID of the containing fedora resource
038     * @return A stream of contained identifiers
039     */
040    Stream<String> getContainsDeleted(Transaction tx, FedoraId fedoraId);
041
042    /**
043     * Return the ID of the containing resource for resourceID.
044     * @param tx The transaction, or null if no transaction
045     * @param resource The FedoraId of the resource to find the containing resource for.
046     * @return The id of the containing resource or null if none found.
047     */
048    String getContainedBy(Transaction tx, final FedoraId resource);
049
050    /**
051     * Mark a contained by relation between the child resource and its parent as deleted.
052     *
053     * @param tx The transaction.
054     * @param parent The containing resource fedoraID.
055     * @param child The contained resource fedoraID.
056     */
057    void removeContainedBy(@Nonnull final Transaction tx, final FedoraId parent, final FedoraId child);
058
059    /**
060     * Mark all relationships to the specified resource as deleted.
061     *
062     * @param tx The transaction.
063     * @param resource The FedoraId of resource to remove.
064     */
065    void removeResource(@Nonnull final Transaction tx, final FedoraId resource);
066
067    /**
068     * Remove all relationships to the specified resource.
069     *
070     * @param tx The transaction.
071     * @param resource The FedoraId of resource to remove.
072     */
073    void purgeResource(@Nonnull final Transaction tx, final FedoraId resource);
074
075    /**
076     * Add a contained by relation between the child resource and its parent.
077     *
078     * @param tx The transaction.
079     * @param parent The containing resource fedoraID.
080     * @param child The contained resource fedoraID.
081     */
082    void addContainedBy(@Nonnull final Transaction tx, final FedoraId parent, final FedoraId child);
083
084    /**
085     * Add a contained by relation between the child resource and its parent for a range of time in the past.
086     *
087     * @param tx The transaction.
088     * @param parent The containing resource fedoraID.
089     * @param child The contained resource fedoraID.
090     * @param startTime The start instant of the containment relationship.
091     * @param endTime The end instant of the containment relationship.
092     */
093    void addContainedBy(@Nonnull final Transaction tx, final FedoraId parent, final FedoraId child,
094                        final Instant startTime, final Instant endTime);
095
096    /**
097     * Commit the changes made in the transaction.
098     * @param tx The transaction.
099     */
100    void commitTransaction(final Transaction tx);
101
102    /**
103     * Rollback the containment index changes in the transaction.
104     * @param tx The transaction.
105     */
106    void rollbackTransaction(final Transaction tx);
107
108    /**
109     * Check if the resourceID exists in the containment index. Which should mean it exists.
110     *
111     * @param tx The transaction, or null if no transaction
112     * @param fedoraId The resource's FedoraId.
113     * @param includeDeleted Include deleted resources in the search.
114     * @return True if it is in the index.
115     */
116    boolean resourceExists(final Transaction tx, final FedoraId fedoraId, final boolean includeDeleted);
117
118    /**
119     * Find the ID for the container of the provided resource by iterating up the path until you find a real resource.
120     * @param tx The transaction, or null if no transaction
121     * @param fedoraId The resource's ID.
122     * @param checkDeleted Whether to include deleted resource (tombstones) in the search.
123     * @return The container ID.
124     */
125    FedoraId getContainerIdByPath(final Transaction tx, final FedoraId fedoraId, final boolean checkDeleted);
126
127    /**
128     * Truncates the containment index. This should only be called when rebuilding the index.
129     */
130    void reset();
131
132    /**
133     * Find whether there are any resources that starts with the ID provided.
134     * @param tx The transaction, or null if no transaction.
135     * @param fedoraId The ID to use to look for other IDs.
136     * @return Are there any matching IDs.
137     */
138    boolean hasResourcesStartingWith(final Transaction tx, final FedoraId fedoraId);
139
140    /**
141     * Find the timestamp of the last child added or deleted
142     * @param tx The transaction, or null if no transaction.
143     * @param fedoraId The ID of the containing resource to check.
144     * @return Timestamp of last child added or deleted or null if none
145     */
146    Instant containmentLastUpdated(final Transaction tx, final FedoraId fedoraId);
147}