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