com.cloudant.sync.datastore

Class AttachmentManager

java.lang.Object

com.cloudant.sync.datastore.AttachmentManager

public class AttachmentManager
extends java.lang.Object

An AttachmentManager handles attachment related tasks: adding, removing and retrieving attachments for documents from disk. It handles both disk read/write and managing the attachment related tables in the datastore's database. Attachments are stored on disk, in the folder specified by the attachmentsDir parameter to each method. AttachmentManager assumes it has sole control of this directory. For example, purging and compaction may delete non-attachment files.

API Status: Private - API users are discouraged from using this class as fields, method signatures, and implementation details may be subject to change

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AttachmentManager.NameGenerationException

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	SQL_ATTACHMENTS_SELECT
static java.lang.String	SQL_ATTACHMENTS_SELECT_ALL

Constructor Summary

Constructors

Constructor and Description
AttachmentManager()

Method Summary

Modifier and Type	Method and Description
static void	addAttachment(SQLDatabase db, java.lang.String attachmentsDir, DocumentRevision rev, PreparedAttachment a)
static void	addAttachmentsToRevision(SQLDatabase db, java.lang.String attachmentsDir, DocumentRevision rev, java.util.List<PreparedAttachment> attachments)
static void	copyAttachment(SQLDatabase db, long parentSequence, long newSequence, java.lang.String filename) Copy a single attachment for a given revision to a new revision.
static void	copyAttachmentsToRevision(SQLDatabase db, java.util.List<SavedAttachment> attachments, DocumentRevision rev)
static java.io.File	fileFromKey(SQLDatabase db, byte[] key, java.lang.String attachmentsDir, boolean allowCreateName) Lookup or create a on disk File representation of blob, in db using key.
static java.util.List<SavedAttachment>	findExistingAttachments(java.util.Collection<? extends Attachment> attachments) Return a list of the existing attachments in the list passed in.
static java.util.List<Attachment>	findNewAttachments(java.util.Collection<? extends Attachment> attachments) Return a list of the new attachments in the list passed in.
static PreparedAttachment	prepareAttachment(java.lang.String attachmentsDir, AttachmentStreamFactory attachmentStreamFactory, Attachment attachment) Creates a PreparedAttachment from attachment, preparing it for insertion into the datastore.
static java.util.List<PreparedAttachment>	prepareAttachments(java.lang.String attachmentsDir, AttachmentStreamFactory attachmentStreamFactory, java.util.List<Attachment> attachments) Download each attachment in attachments to a temporary location, and return a list of attachments suitable for passing to setAttachments.
static void	purgeAttachments(SQLDatabase db, java.lang.String attachmentsDir) Called by BasicDatastore on the execution queue, this needs have the db passed ot it

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SQL_ATTACHMENTS_SELECT

public static final java.lang.String SQL_ATTACHMENTS_SELECT

See Also:

Constant Field Values

SQL_ATTACHMENTS_SELECT_ALL

public static final java.lang.String SQL_ATTACHMENTS_SELECT_ALL

See Also:

Constant Field Values

Constructor Detail

AttachmentManager

public AttachmentManager()

Method Detail

addAttachmentsToRevision

public static void addAttachmentsToRevision(SQLDatabase db,
                                            java.lang.String attachmentsDir,
                                            DocumentRevision rev,
                                            java.util.List<PreparedAttachment> attachments)
                                     throws AttachmentNotSavedException

Throws:

AttachmentNotSavedException

addAttachment

public static void addAttachment(SQLDatabase db,
                                 java.lang.String attachmentsDir,
                                 DocumentRevision rev,
                                 PreparedAttachment a)
                          throws AttachmentNotSavedException

Throws:

AttachmentNotSavedException

prepareAttachment

public static PreparedAttachment prepareAttachment(java.lang.String attachmentsDir,
                                                   AttachmentStreamFactory attachmentStreamFactory,
                                                   Attachment attachment)
                                            throws AttachmentException

Creates a PreparedAttachment from attachment, preparing it for insertion into the datastore.

Parameters:

attachmentStreamFactory -

attachment - Attachment to prepare for insertion into datastore

Returns:

PreparedAttachment, which can be used in addAttachment methods

Throws:

AttachmentException - if there was an error preparing the attachment, e.g., reading attachment data.

findExistingAttachments

public static java.util.List<SavedAttachment> findExistingAttachments(java.util.Collection<? extends Attachment> attachments)

Return a list of the existing attachments in the list passed in.

Parameters:

attachments - Attachments to search.

Returns:

List of attachments which already exist in the attachment store, or an empty list if none.

findNewAttachments

public static java.util.List<Attachment> findNewAttachments(java.util.Collection<? extends Attachment> attachments)

Return a list of the new attachments in the list passed in.

Parameters:

attachments - Attachments to search.

Returns:

List of attachments which need adding to the attachment store, or an empty list if none.

prepareAttachments

public static java.util.List<PreparedAttachment> prepareAttachments(java.lang.String attachmentsDir,
                                                                    AttachmentStreamFactory attachmentStreamFactory,
                                                                    java.util.List<Attachment> attachments)
                                                             throws AttachmentException

Download each attachment in attachments to a temporary location, and return a list of attachments suitable for passing to setAttachments. Typically attachments is found via a call to findNewAttachments(java.util.Collection<? extends com.cloudant.sync.datastore.Attachment>).

Parameters:

attachments - List of attachments to prepare.

Returns:

Attachments prepared for inserting into attachment store.

Throws:

AttachmentException

See Also:

findNewAttachments(java.util.Collection<? extends com.cloudant.sync.datastore.Attachment>)

copyAttachmentsToRevision

public static void copyAttachmentsToRevision(SQLDatabase db,
                                             java.util.List<SavedAttachment> attachments,
                                             DocumentRevision rev)
                                      throws DatastoreException

Throws:

DatastoreException

copyAttachment

public static void copyAttachment(SQLDatabase db,
                                  long parentSequence,
                                  long newSequence,
                                  java.lang.String filename)
                           throws java.sql.SQLException

Copy a single attachment for a given revision to a new revision.

Parameters:

db - database to use

parentSequence - identifies sequence number of revision to copy attachment data from

newSequence - identifies sequence number of revision to copy attachment data to

filename - filename of attachment to copy

Throws:

java.sql.SQLException

purgeAttachments

public static void purgeAttachments(SQLDatabase db,
                                    java.lang.String attachmentsDir)

Called by BasicDatastore on the execution queue, this needs have the db passed ot it

Parameters:

db - database to purge attachments from

fileFromKey

public static java.io.File fileFromKey(SQLDatabase db,
                                       byte[] key,
                                       java.lang.String attachmentsDir,
                                       boolean allowCreateName)
                                throws AttachmentException

Lookup or create a on disk File representation of blob, in db using key. Existing attachments will have an entry in db, so the method just looks this up and returns the File object for the path. For new attachments, the key doesn't already have an associated filename, one is generated and inserted into the database before returning a File object for blob associated with key.

Parameters:

db - database to use.

key - key to lookup filename for.

attachmentsDir - Root directory for attachment blobs.

allowCreateName - if the is no existing mapping, whether one should be created and returned. If false, and no existing mapping, AttachmentException is thrown.

Returns:

File object for blob associated with key.

Throws:

AttachmentException - if a mapping doesn't exist and allowCreateName is false or if the name generation process fails.