001/**
002 * Copyright 2015 DuraSpace, Inc.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.fcrepo.serialization;
017
018import java.io.IOException;
019import java.io.InputStream;
020import java.io.OutputStream;
021
022import javax.jcr.RepositoryException;
023import javax.jcr.Session;
024
025import org.fcrepo.kernel.models.FedoraResource;
026import org.fcrepo.kernel.exception.InvalidChecksumException;
027import org.springframework.stereotype.Component;
028
029/**
030 * Interface for serializing/deserializing a FedoraObject
031 * to some transportable format
032 *
033 * @author cbeer
034 */
035@Component
036public interface FedoraObjectSerializer {
037    // Key for jcr/xml serialization
038    final String JCR_XML = "jcr/xml";
039    /**
040     * Get the key for the serializer (that will be
041     * used at the REST API to identify the format)
042     * @return serializer key
043     */
044    String getKey();
045
046    /**
047     * Get the media type for the serialized output
048     * (so we can send the right mime type as appropriate)
049     * @return serializer output media type
050     */
051    String getMediaType();
052
053    /**
054     * Determines whether this FedoraObjectSerializer can be used to
055     * serialize the given resource.  A FedoraObjectSerializer
056     * implementation may use any arbitrary criteria to determine
057     * which resources it can serialize, so this method should be
058     * invoked to avoid an InvalidSerializationFormatException from
059     * {@link #serialize}.
060     * @param resource the resource
061     * @return whether this can be used to serialize the given resource
062     */
063    boolean canSerialize(final FedoraResource resource);
064
065    /**
066     * Serialize a FedoraObject into some format with options for recurse
067     * and skipBinary, and write it to the given OutputStream
068     *
069     * @param obj the obj
070     * @param out the out
071     * @param skipBinary skip binary
072     * @param recurse the recurse
073     * @throws RepositoryException if repository exception occurred
074     * @throws IOException if IO exception occurred
075     * @throws org.fcrepo.serialization.InvalidSerializationFormatException if invalid serialization occurred
076     */
077    void serialize(final FedoraResource obj, final OutputStream out, final boolean skipBinary, final boolean recurse)
078                    throws RepositoryException, IOException, InvalidSerializationFormatException;
079
080    /**
081     * Read the given InputStream and de-serialize the content
082     * into new nodes in the given session using the given path
083     * as the parent node
084     *
085     * @param session the session
086     * @param path the path
087     * @param stream the stream
088     * @throws IOException if IO exception occurred
089     * @throws RepositoryException if repository exception occurred
090     * @throws InvalidChecksumException if invalid checksum exception occurred
091     * @throws org.fcrepo.serialization.InvalidSerializationFormatException if invadlid serialization occurred
092     */
093    void deserialize(final Session session, final String path,
094            final InputStream stream) throws IOException, RepositoryException,
095            InvalidChecksumException, InvalidSerializationFormatException;
096
097}