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.models;
019
020import java.net.URI;
021import java.time.Instant;
022
023import java.util.List;
024import java.util.Set;
025import java.util.stream.Stream;
026
027import org.apache.jena.rdf.model.Resource;
028
029import org.fcrepo.kernel.api.RdfStream;
030import org.fcrepo.kernel.api.TripleCategory;
031import org.fcrepo.kernel.api.exception.AccessDeniedException;
032import org.fcrepo.kernel.api.exception.MalformedRdfException;
033import org.fcrepo.kernel.api.identifiers.IdentifierConverter;
034
035import org.apache.jena.rdf.model.Model;
036
037/**
038 * @author ajs6f
039 * @since Jan 10, 2014
040 */
041public interface FedoraResource {
042
043    /**
044     * Get the path to the resource
045     * @return path
046     */
047    String getPath();
048
049    /**
050     * Get the children of this resource
051     * @return a stream of Fedora resources
052     */
053    default Stream<FedoraResource> getChildren() {
054        return getChildren(false);
055    }
056
057    /**
058     * Get the children of this resource, possibly recursively
059     * @param recursive whether to recursively fetch child resources
060     * @return a stream of Fedora resources
061     */
062    Stream<FedoraResource> getChildren(Boolean recursive);
063
064    /**
065     * Get the container of this resource
066     * @return the container of this resource
067     */
068    FedoraResource getContainer();
069
070    /**
071     * Get the Original Resource for which this resource is a memento. If this resource is not a memento,
072     * then it is the original.
073     *
074     * @return the original resource for this
075     */
076    FedoraResource getOriginalResource();
077
078    /**
079     * Get the TimeMap/LDPCv of this resource
080     *
081     * @return the container for TimeMap/LDPCv of this resource
082     */
083    FedoraResource getTimeMap();
084
085    /**
086     * Retrieve the mementoDatetime property and return it as an Instant
087     *
088     * @return the Instant for this resource
089     */
090    Instant getMementoDatetime();
091
092    /**
093     * Returns true if this resource is a Memento.
094     *
095     * @return true if the resource is a Memento.
096     */
097    boolean isMemento();
098
099    /**
100     * Returns true if this resource is an ACL.
101     *
102     * @return true if the resource is an ACL.
103     */
104    boolean isAcl();
105
106    /**
107     * Retrieve the Memento with the closest datetime to the request.
108     *
109     * @param mementoDatetime The requested date time.
110     * @return The closest Memento or null.
111     */
112    FedoraResource findMementoByDatetime(Instant mementoDatetime);
113
114    /**
115     * Get the ACL of this resource
116     * @return the container for ACL of this resource
117     */
118    FedoraResource getAcl();
119
120    /**
121     * Create the ACL for this resource if it doesn't exist
122     * @return the container for ACL of this resource
123     */
124    FedoraResource findOrCreateAcl();
125
126    /**
127     * Get the child of this resource at the given path
128     *
129     * @param relPath the given path
130     * @return the child of this resource
131     */
132    FedoraResource getChild(String relPath);
133
134    /**
135     * Does this resource have a property
136     * @param relPath the given path
137     * @return the boolean value whether the resource has a property
138     */
139    boolean hasProperty(String relPath);
140
141    /**
142     * Delete this resource, and any inbound references to it
143     */
144    void delete();
145
146    /**
147     * Get the date this resource was created
148     * @return created date
149     */
150    Instant getCreatedDate();
151
152    /**
153     * Get the date this resource was last modified
154     * @return last modified date
155     */
156    Instant getLastModifiedDate();
157
158    /**
159     * Check if this object uses a given RDF type
160     *
161     * <p>Note: the type parameter should be in prefixed short form, so ldp:Container or ex:Image
162     * are both acceptable types. This method does not assume any jcr to fedora prefix mappings are
163     * managed by the implementation, so hasType("jcr:frozenNode") is a valid use of this method.</p>
164     *
165     * @param type the given type
166     * @return whether the object has the given type
167     */
168    boolean hasType(final String type);
169
170    /**
171     * Get the RDF:type values for this resource
172     * @return a list of types for this resource
173     */
174    List<URI> getTypes();
175
176    /**
177     * Add an RDF:type value to the resource
178     *
179     * <p>Note: the type parameter should be in prefixed short form, so ldp:Container or ex:Image
180     * are both acceptable types. This method does not assume any jcr to fedora prefix mappings are
181     * managed by the implementation, so hasType("jcr:frozenNode") is a valid use of this method.</p>
182     *
183     * @param type the type to add
184     */
185    void addType(final String type);
186
187    /**
188     * Update the provided properties with a SPARQL Update query. The updated
189     * properties may be serialized to the persistence layer.
190     *
191     * @param idTranslator the property of idTranslator
192     * @param sparqlUpdateStatement sparql update statement
193     * @param originalTriples original triples
194     * @throws MalformedRdfException if malformed rdf exception occurred
195     * @throws AccessDeniedException if access denied in updating properties
196     */
197    void updateProperties(final IdentifierConverter<Resource, FedoraResource> idTranslator,
198                          final String sparqlUpdateStatement,
199                          final RdfStream originalTriples) throws MalformedRdfException, AccessDeniedException;
200
201    /**
202     * Return the RDF properties of this object using the provided context
203     * @param idTranslator the property of idTranslator
204     * @param context the context
205     * @return the rdf properties of this object using the provided context
206     */
207    RdfStream getTriples(final IdentifierConverter<Resource, FedoraResource> idTranslator,
208                         final TripleCategory context);
209
210    /**
211     * Return the RDF properties of this object using the provided contexts
212     * @param idTranslator the property of idTranslator
213     * @param contexts the provided contexts
214     * @return the rdf properties of this object
215     */
216    RdfStream getTriples(final IdentifierConverter<Resource, FedoraResource> idTranslator,
217                         final Set<? extends TripleCategory> contexts);
218
219    /**
220     * Check if a resource was created in this session
221     * 
222     * @return if resource created in this session
223     */
224    Boolean isNew();
225
226    /**
227     * Replace the properties of this object with the properties from the given
228     * model
229     *
230     * @param idTranslator the given property of idTranslator
231     * @param inputModel the input model
232     * @param originalTriples the original triples
233     * @throws MalformedRdfException if malformed rdf exception occurred
234     */
235    void replaceProperties(final IdentifierConverter<Resource, FedoraResource> idTranslator,
236                                final Model inputModel,
237                                final RdfStream originalTriples) throws MalformedRdfException;
238
239    /**
240     * Construct an ETag value for the resource.
241     *
242     * @return constructed etag value
243     */
244    String getEtagValue();
245
246    /**
247     * Check if a resource is an original resource
248     * (ie versionable, as opposed to non-versionable resources
249     * like mementos, timemaps, and acls).
250     * @return whether the resource is an original resource.
251     */
252    boolean isOriginalResource();
253
254    /**
255     * Get the description for this resource
256     * @return the description for this resource
257     */
258    FedoraResource getDescription();
259
260    /**
261     * Get the resource described by this resource
262     * @return the resource being described
263     */
264    FedoraResource getDescribedResource();
265}