org.apache.chemistry.opencmis.client.api.Document Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.chemistry.opencmis.client.api;
import java.io.OutputStream;
import java.math.BigInteger;
import java.util.List;
import java.util.Map;
import org.apache.chemistry.opencmis.commons.data.Ace;
import org.apache.chemistry.opencmis.commons.data.ContentStream;
import org.apache.chemistry.opencmis.commons.enums.VersioningState;
import org.apache.chemistry.opencmis.commons.exceptions.CmisContentAlreadyExistsException;
/**
* CMIS document interface.
*
* @cmis 1.0
*/
public interface Document extends FileableCmisObject, DocumentProperties {
/**
* Returns the object type as a document type.
*
* @return the document type
*
* @throws ClassCastException
* if the object type is not a document type
*
* @cmis 1.0
*/
DocumentType getDocumentType();
/**
* Returns whether the document is versionable or not.
*
* @return {@code true} if the document is versionable, {@code false} if the
* document is not versionable or if it's unknown
*
* @cmis 1.0
*/
boolean isVersionable();
// object service
/**
* Deletes this document and all its versions.
*
* @cmis 1.0
*/
void deleteAllVersions();
/**
* Retrieves the content stream of this document.
*
* @return the content stream, or {@code null} if the document has no
* content
*
* @cmis 1.0
*/
ContentStream getContentStream();
/**
* Retrieves the content stream of this document.
*
* @param offset
* the offset of the stream or {@code null} to read the stream
* from the beginning
* @param length
* the maximum length of the stream or {@code null} to read to
* the end of the stream
*
* @return the content stream, or {@code null} if the document has no
* content
*
* @cmis 1.0
*/
ContentStream getContentStream(BigInteger offset, BigInteger length);
/**
* Retrieves the content stream that is associated with the given stream ID.
* This is usually a rendition of the document.
*
* @param streamId
* the stream ID
*
* @return the content stream, or {@code null} if no content is associated
* with this stream ID
*
* @cmis 1.0
*/
ContentStream getContentStream(String streamId);
/**
* Retrieves the content stream that is associated with the given stream ID.
* This is usually a rendition of the document.
*
* @param streamId
* the stream ID
* @param offset
* the offset of the stream or {@code null} to read the stream
* from the beginning
* @param length
* the maximum length of the stream or {@code null} to read to
* the end of the stream
*
* @return the content stream, or {@code null} if no content is associated
* with this stream ID
*
* @cmis 1.0
*/
ContentStream getContentStream(String streamId, BigInteger offset, BigInteger length);
/**
* Returns the content URL of the document if the binding supports content
* URLs.
*
* Depending on the repository and the binding, the server might not return
* the content but an error message. Authentication data is not attached.
* That is, a user may have to re-authenticate to get the content.
*
* @return the content URL of the document or {@code null} if the binding
* does not support content URLs
*/
public String getContentUrl();
/**
* Returns the content URL of the document or a rendition if the binding
* supports content URLs.
*
* Depending on the repository and the binding, the server might not return
* the content but an error message. Authentication data is not attached.
* That is, a user may have to re-authenticate to get the content.
*
* @param streamId
* the ID of the rendition or {@code null} for the document
*
* @return the content URL of the document or rendition or {@code null} if
* the binding does not support content URLs
*/
public String getContentUrl(String streamId);
/**
* Sets a new content stream for the document and refreshes this object
* afterwards. If the repository created a new version, this new document is
* returned. Otherwise the current document is returned.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @param contentStream
* the content stream
* @param overwrite
* if this parameter is set to {@code false} and the document
* already has content, the repository throws a
* {@link CmisContentAlreadyExistsException}
*
* @return the updated document, or {@code null} if the repository did not
* return an object ID
*
* @see ObjectFactory#createContentStream(String, long, String,
* java.io.InputStream)
*
* @cmis 1.0
*/
Document setContentStream(ContentStream contentStream, boolean overwrite);
/**
* Sets a new content stream for the document. If the repository created a
* new version, the object ID of this new version is returned. Otherwise the
* object ID of the current document is returned.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @param contentStream
* the content stream
* @param overwrite
* if this parameter is set to {@code false} and the document
* already has content, the repository throws a
* {@link CmisContentAlreadyExistsException}
* @param refresh
* if this parameter is set to {@code true}, this object will be
* refreshed after the new content has been set
*
* @return the updated object ID, or {@code null} if the repository did not
* return an object ID
*
* @see ObjectFactory#createContentStream(String, long, String,
* java.io.InputStream)
*
* @cmis 1.0
*/
ObjectId setContentStream(ContentStream contentStream, boolean overwrite, boolean refresh);
/**
* Appends a content stream to the content stream of the document and
* refreshes this object afterwards. If the repository created a new
* version, this new document is returned. Otherwise the current document is
* returned.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @param contentStream
* the content stream
* @param isLastChunk
* indicates if this stream is the last chunk of the content
*
* @return the updated document, or {@code null} if the repository did not
* return an object ID
*
* @see ObjectFactory#createContentStream(String, long, String,
* java.io.InputStream)
*
* @cmis 1.1
*/
Document appendContentStream(ContentStream contentStream, boolean isLastChunk);
/**
* Appends a content stream to the content stream of the document. If the
* repository created a new version, the object ID of this new version is
* returned. Otherwise the object ID of the current document is returned.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @param contentStream
* the content stream
* @param isLastChunk
* indicates if this stream is the last chunk of the content
* @param refresh
* if this parameter is set to {@code true}, this object will be
* refreshed after the content stream has been appended
*
* @return the updated object ID, or {@code null} if the repository did not
* return an object ID
*
* @cmis 1.1
*/
ObjectId appendContentStream(ContentStream contentStream, boolean isLastChunk, boolean refresh);
/**
* Removes the current content stream from the document and refreshes this
* object afterwards. If the repository created a new version, this new
* document is returned. Otherwise the current document is returned.
*
* @return the updated document, or {@code null} if the repository did not
* return an object ID
*
* @cmis 1.0
*/
Document deleteContentStream();
/**
* Removes the current content stream from the document. If the repository
* created a new version, the object ID of this new version is returned.
* Otherwise the object ID of the current document is returned.
*
* @param refresh
* if this parameter is set to {@code true}, this object will be
* refreshed after the content stream has been deleted
*
* @return the updated document, or {@code null} if the repository did not
* return an object ID
*
* @cmis 1.0
*/
ObjectId deleteContentStream(boolean refresh);
/**
* Creates an {@link OutputStream} stream object that can be used to
* overwrite the current content of the document.
*
* @param filename
* the file name
* @param mimeType
* the MIME type
* @return the OutputStream object
*
* @cmis 1.1
*/
OutputStream createOverwriteOutputStream(String filename, String mimeType);
/**
* Creates an {@link OutputStream} stream object that can be used to
* overwrite the current content of the document.
*
* @param filename
* the file name
* @param mimeType
* the MIME type
* @param bufferSize
* buffer size in bytes
* @return the OutputStream object
*
* @cmis 1.1
*/
OutputStream createOverwriteOutputStream(String filename, String mimeType, int bufferSize);
/**
* Creates an {@link OutputStream} stream object that can be used to append
* content the current content of the document.
*
* @return the OutputStream object
*
* @cmis 1.1
*/
OutputStream createAppendOutputStream();
/**
* Creates an {@link OutputStream} stream object that can be used to append
* content the current content of the document.
*
* @param bufferSize
* buffer size in bytes
* @return the OutputStream object
*
* @cmis 1.1
*/
OutputStream createAppendOutputStream(int bufferSize);
// versioning service
/**
* Checks out the document and returns the object ID of the PWC (private
* working copy).
*
* @return PWC object ID
*
* @cmis 1.0
*/
ObjectId checkOut();
/**
* If this is a PWC (private working copy) the check out will be reversed.
* If this is not a PWC it an exception will be thrown.
*
* @cmis 1.0
*/
void cancelCheckOut();
/**
* If this is a PWC (private working copy) it performs a check in. If this
* is not a PWC it an exception will be thrown.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @return new document ID
*
* @cmis 1.0
*/
ObjectId checkIn(boolean major, Map properties, ContentStream contentStream, String checkinComment,
List policies, List addAces, List removeAces);
/**
* If this is a PWC (private working copy) it performs a check in. If this
* is not a PWC it an exception will be thrown.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @return new document ID
*
* @cmis 1.0
*/
ObjectId checkIn(boolean major, Map properties, ContentStream contentStream, String checkinComment);
/**
* Fetches the latest major or minor version of this document.
*
* @param major
* if {@code true} the latest major version will be returned,
* otherwise the very last version will be returned
*
* @return the latest document object
*
* @cmis 1.0
*/
Document getObjectOfLatestVersion(boolean major);
/**
* Fetches the latest major or minor version of this document using the
* given {@link OperationContext}.
*
* @param major
* if {@code true} the latest major version will be returned,
* otherwise the very last version will be returned
*
* @return the latest document object
*
* @cmis 1.0
*/
Document getObjectOfLatestVersion(boolean major, OperationContext context);
/**
* Fetches all versions of this document.
*
* The behavior of this method is undefined if the document is not
* versionable and can be different for each repository.
*
* @return all versions of the version series, sorted by
* {@code cmis:creationDate} descending and preceded by the PWC, if
* one exists, not {@code null}
*
* @cmis 1.0
*/
List getAllVersions();
/**
* Fetches all versions of this document using the given
* {@link OperationContext}.
*
* The behavior of this method is undefined if the document is not
* versionable and can be different for each repository.
*
* @return all versions of the version series, sorted by
* {@code cmis:creationDate} descending and preceded by the PWC, if
* one exists, not {@code null}
*
* @cmis 1.0
*/
List getAllVersions(OperationContext context);
/**
* Creates a copy of this document, including content.
*
* @param targetFolderId
* the ID of the target folder, {@code null} to create an unfiled
* document
*
* @return the new document object
*
* @cmis 1.0
*/
Document copy(ObjectId targetFolderId);
/**
* Creates a copy of this document, including content.
*
* @param targetFolderId
* the ID of the target folder, {@code null} to create an unfiled
* document
*
* @return the new document object or {@code null} if the parameter
* {@code context} was set to {@code null}
*
* @cmis 1.0
*/
Document copy(ObjectId targetFolderId, Map properties, VersioningState versioningState,
List policies, List addACEs, List removeACEs, OperationContext context);
}