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 static java.time.format.DateTimeFormatter.RFC_1123_DATE_TIME; 021 022import java.io.InputStream; 023import java.net.URI; 024import java.time.Instant; 025import java.time.ZoneId; 026import java.time.format.DateTimeFormatter; 027import java.util.Collection; 028 029import org.apache.jena.rdf.model.Resource; 030import org.apache.jena.riot.Lang; 031import org.fcrepo.kernel.api.FedoraSession; 032import org.fcrepo.kernel.api.exception.InvalidChecksumException; 033import org.fcrepo.kernel.api.identifiers.IdentifierConverter; 034import org.fcrepo.kernel.api.models.FedoraBinary; 035import org.fcrepo.kernel.api.models.FedoraResource; 036import org.fcrepo.kernel.api.services.policy.StoragePolicyDecisionPoint; 037 038/** 039 * Service for creating versions of resources 040 * 041 * @author bbpennel 042 * @author whikloj 043 * @since Feb 19, 2014 044 */ 045public interface VersionService { 046 047 /** 048 * To format a datetime for use as a Memento path. 049 */ 050 DateTimeFormatter MEMENTO_LABEL_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMddHHmmss") 051 .withZone(ZoneId.of("UTC")); 052 053 /** 054 * To format a datetime as RFC-1123 with correct timezone. 055 */ 056 DateTimeFormatter MEMENTO_RFC_1123_FORMATTER = RFC_1123_DATE_TIME.withZone(ZoneId.of("UTC")); 057 058 /** 059 * Explicitly creates a version for the resource at the path provided. 060 * 061 * @param session the session in which the resource resides 062 * @param resource the resource to version 063 * @param idTranslator translator for producing URI of resources 064 * @param dateTime the date/time of the version 065 * @return the version 066 */ 067 FedoraResource createVersion(FedoraSession session, FedoraResource resource, 068 IdentifierConverter<Resource, FedoraResource> idTranslator, Instant dateTime); 069 070 /** 071 * Explicitly creates a version for the resource at the path provided for the date/time provided. 072 * 073 * @param session the session in which the resource resides 074 * @param resource the resource to version 075 * @param idTranslator translator for producing URI of resources 076 * @param dateTime the date/time of the version 077 * @param rdfInputStream if provided, this stream will provide the properties of the new memento. If null, then 078 * the state of the current resource will be used. 079 * @param rdfFormat RDF language format name 080 * @return the version 081 */ 082 FedoraResource createVersion(FedoraSession session, FedoraResource resource, 083 IdentifierConverter<Resource, FedoraResource> idTranslator, Instant dateTime, InputStream rdfInputStream, 084 Lang rdfFormat); 085 086 /** 087 * Explicitly creates a version of a binary resource. If contentStream is provided, then it will be used as the 088 * content of the binary memento. Otherwise, the current state of the binary will be used. 089 * 090 * @param session the session in which the resource resides 091 * @param resource the binary resource to version 092 * @param dateTime the date/time of the version 093 * @param contentStream if provided, the content in this stream will be used as the content of the new binary 094 * memento. If null, then the current state of the binary will be used. 095 * @param checksums Collection of checksum URIs of the content (optional) 096 * @param storagePolicyDecisionPoint optional storage policy 097 * @throws InvalidChecksumException if there are errors applying checksums 098 * @return the version 099 */ 100 FedoraBinary createBinaryVersion(FedoraSession session, 101 FedoraBinary resource, 102 Instant dateTime, 103 InputStream contentStream, 104 Collection<URI> checksums, 105 StoragePolicyDecisionPoint storagePolicyDecisionPoint) 106 throws InvalidChecksumException; 107 108 /** 109 * Explicitly creates a version of a binary resource from the current state of that binary. 110 * 111 * @param session the session in which the resource resides 112 * @param resource the binary resource to version 113 * @param dateTime the date/time of the version 114 * @param storagePolicyDecisionPoint optional storage policy 115 * @return the version 116 * @throws InvalidChecksumException on error 117 */ 118 FedoraBinary createBinaryVersion(FedoraSession session, FedoraBinary resource, Instant dateTime, 119 StoragePolicyDecisionPoint storagePolicyDecisionPoint) 120 throws InvalidChecksumException; 121 122 /** 123 * @param session the session in which the resource resides 124 * @param resource the binary resource to version 125 * @param dateTime the date/time of the version 126 * @param checksums Collection of checksum URIs of the content (optional) 127 * @param externalHandling What type of handling the external resource needs (proxy or redirect) 128 * @param externalUrl Url for the external resourcej 129 * @return the version 130 * @throws InvalidChecksumException if there are errors applying checksums 131 */ 132 FedoraBinary createExternalBinaryVersion(final FedoraSession session, 133 final FedoraBinary resource, 134 final Instant dateTime, 135 final Collection<URI> checksums, 136 final String externalHandling, 137 final String externalUrl) 138 throws InvalidChecksumException; 139}