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.services;
019
020import org.fcrepo.kernel.api.RdfStream;
021import org.fcrepo.kernel.api.Transaction;
022import org.fcrepo.kernel.api.identifiers.FedoraId;
023import org.fcrepo.kernel.api.models.FedoraResource;
024
025/**
026 * Service to retrieve references to repository resources.
027 * @author whikloj
028 * @since 6.0.0
029 */
030public interface ReferenceService {
031
032    /**
033     * Return a RDF stream of statements referring to the provided resource.
034     *
035     * @param tx the transaction or null if no transaction.
036     * @param resource the resource to get inbound references for.
037     * @return RDF stream of inbound reference triples.
038     */
039    RdfStream getInboundReferences(final Transaction tx, final FedoraResource resource);
040
041    /**
042     * Delete all references from a resource to any other resource.
043     *
044     * @param tx the transaction
045     * @param resourceId the ID of the resource referencing others.
046     */
047    void deleteAllReferences(final Transaction tx, final FedoraId resourceId);
048
049    /**
050     * Parse the stream of triples for references, add any new ones and remove any missing ones.
051     * @param tx the transaction
052     * @param resourceId the subject ID of the triples.
053     * @param userPrincipal the user who's action is updating references.
054     * @param rdfStream the RDF stream.
055     */
056    void updateReferences(final Transaction tx, final FedoraId resourceId, final String userPrincipal,
057                          final RdfStream rdfStream);
058
059    /**
060     * Commit any pending references.
061     * @param tx the transaction.
062     */
063    void commitTransaction(final Transaction tx);
064
065    /**
066     * Rollback any pending references.
067     * @param tx the transaction.
068     */
069    void rollbackTransaction(final Transaction tx);
070
071    /**
072     * Truncates the reference index. This should only be called when rebuilding the index.
073     */
074    void reset();
075}