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 a TimeMap.
101     *
102     * @return true if the resource is a TimeMap.
103     */
104    boolean isTimeMap();
105
106    /**
107     * Returns true if this resource is an ACL.
108     *
109     * @return true if the resource is an ACL.
110     */
111    boolean isAcl();
112
113    /**
114     * Retrieve the Memento with the closest datetime to the request.
115     *
116     * @param mementoDatetime The requested date time.
117     * @return The closest Memento or null.
118     */
119    FedoraResource findMementoByDatetime(Instant mementoDatetime);
120
121    /**
122     * Get the ACL of this resource
123     * @return the container for ACL of this resource
124     */
125    FedoraResource getAcl();
126
127    /**
128     * Create the ACL for this resource if it doesn't exist
129     * @return the container for ACL of this resource
130     */
131    FedoraResource findOrCreateAcl();
132
133    /**
134     * Get the child of this resource at the given path
135     *
136     * @param relPath the given path
137     * @return the child of this resource
138     */
139    FedoraResource getChild(String relPath);
140
141    /**
142     * Does this resource have a property
143     * @param relPath the given path
144     * @return the boolean value whether the resource has a property
145     */
146    boolean hasProperty(String relPath);
147
148    /**
149     * Delete this resource, and any inbound references to it
150     */
151    void delete();
152
153    /**
154     * Get the date this resource was created
155     * @return created date
156     */
157    Instant getCreatedDate();
158
159    /**
160     * Get the date this resource was last modified
161     * @return last modified date
162     */
163    Instant getLastModifiedDate();
164
165    /**
166     * Check if this object uses a given RDF type
167     *
168     * <p>Note: the type parameter should be in prefixed short form, so ldp:Container or ex:Image
169     * are both acceptable types. This method does not assume any jcr to fedora prefix mappings are
170     * managed by the implementation, so hasType("jcr:lastModified") is a valid use of this method.</p>
171     *
172     * @param type the given type
173     * @return whether the object has the given type
174     */
175    boolean hasType(final String type);
176
177    /**
178     * Get the RDF:type values for this resource
179     * @return a list of types for this resource
180     */
181    List<URI> getTypes();
182
183    /**
184     * Add an RDF:type value to the resource
185     *
186     * <p>Note: the type parameter should be in prefixed short form, so ldp:Container or ex:Image
187     * are both acceptable types. This method does not assume any jcr to fedora prefix mappings are
188     * managed by the implementation, so hasType("jcr:lastModified") is a valid use of this method.</p>
189     *
190     * @param type the type to add
191     */
192    void addType(final String type);
193
194    /**
195     * Update the provided properties with a SPARQL Update query. The updated
196     * properties may be serialized to the persistence layer.
197     *
198     * @param idTranslator the property of idTranslator
199     * @param sparqlUpdateStatement sparql update statement
200     * @param originalTriples original triples
201     * @throws MalformedRdfException if malformed rdf exception occurred
202     * @throws AccessDeniedException if access denied in updating properties
203     */
204    void updateProperties(final IdentifierConverter<Resource, FedoraResource> idTranslator,
205                          final String sparqlUpdateStatement,
206                          final RdfStream originalTriples) throws MalformedRdfException, AccessDeniedException;
207
208    /**
209     * Return the RDF properties of this object using the provided context
210     * @param idTranslator the property of idTranslator
211     * @param context the context
212     * @return the rdf properties of this object using the provided context
213     */
214    RdfStream getTriples(final IdentifierConverter<Resource, FedoraResource> idTranslator,
215                         final TripleCategory context);
216
217    /**
218     * Return the RDF properties of this object using the provided contexts
219     * @param idTranslator the property of idTranslator
220     * @param contexts the provided contexts
221     * @return the rdf properties of this object
222     */
223    RdfStream getTriples(final IdentifierConverter<Resource, FedoraResource> idTranslator,
224                         final Set<? extends TripleCategory> contexts);
225
226    /**
227     * Check if a resource was created in this session
228     * 
229     * @return if resource created in this session
230     */
231    Boolean isNew();
232
233    /**
234     * Replace the properties of this object with the properties from the given
235     * model
236     *
237     * @param idTranslator the given property of idTranslator
238     * @param inputModel the input model
239     * @param originalTriples the original triples
240     * @throws MalformedRdfException if malformed rdf exception occurred
241     */
242    void replaceProperties(final IdentifierConverter<Resource, FedoraResource> idTranslator,
243                                final Model inputModel,
244                                final RdfStream originalTriples) throws MalformedRdfException;
245
246    /**
247     * Construct an ETag value for the resource.
248     *
249     * @return constructed state-token value
250     */
251    String getEtagValue();
252
253    /**
254     * Construct a State Token value for the resource.
255     *
256     * @return constructed state-token value
257     */
258    String getStateToken();
259    /**
260     * Check if a resource is an original resource
261     * (ie versionable, as opposed to non-versionable resources
262     * like mementos, timemaps, and acls).
263     * @return whether the resource is an original resource.
264     */
265    boolean isOriginalResource();
266
267    /**
268     * Get the description for this resource
269     * @return the description for this resource
270     */
271    FedoraResource getDescription();
272
273    /**
274     * Get the resource described by this resource
275     * @return the resource being described
276     */
277    FedoraResource getDescribedResource();
278}