de.ipcon.db.blob

Class ServerFileVault

java.lang.Object

de.ipcon.db.blob.ServerFileVault

All Implemented Interfaces:

FileVaultI, ServerFileVaultI, IntegrityCheckingServerFileVaultI

public class ServerFileVault
extends java.lang.Object
implements ServerFileVaultI

This class is a singleton which provides transactional access to files (Binary Large Objects or BLOBs connected to database-objects) using TransactionalFileI objects.

It manages all physical storage for BLOBs, ensuring that file operations (like saving, changing, or deleting) are atomic and consistent with database transactions. It utilizes a set of specialized directories (storage, backup, temporary) and a temporary file per BLOB to facilitate this transactional safety.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FILEEXTENSION_BLOB
static java.lang.String	FILEEXTENSION_LOG
static org.apache.log4j.Logger	log

Constructor Summary

Constructors

Constructor and Description
ServerFileVault(java.io.File _newFilesDir, java.io.File _storageDir, java.io.File _backupDir, java.io.File _lostAndFoundDir, java.io.File _atticDir) Private constructor for the ServerFileVault singleton.
ServerFileVault(java.io.File _newFilesDir, java.io.File _storageDir, java.io.File _backupDir, java.io.File _lostAndFoundDir, java.io.File _atticDir, DBManLocalI _dbm)

Method Summary

Modifier and Type	Method and Description
java.lang.String	getBackupFileName(java.lang.Long boid, java.lang.Long bpid)
java.lang.String	getBackupFileNameTemp(java.lang.Long boid, java.lang.Long bpid)
java.io.File	getBLOB(java.lang.Long boid) get the BLOB belonging to BO[id].
java.io.File	getBLOB(java.lang.Long boid, java.lang.Long backuppingBPId) get the BLOB belonging to BO[id].
InitialBLOBTransferMetaDataContainer	getBLOBBOIdsForIntitialBLOBCopy(java.util.Map idsAndVFilesOnSyncNode, java.util.List pendingBLOBChangeBOIdsOnSyncNode, java.util.List pendingBLOBChangeBOIdsOnAuthNode) Returns the Ids of all local BLOBs, unless they are older or have the same hash as listed in the passed Map This method is called on the receiving end of command CMD_COPYBLOBS to determine which BLOBs exist locally, that do not exist on the sender's end or have a different hash.
VFile	getBLOBInfo(java.lang.Long id) gathers information about the BLOB belonging to BO[i].
VFile	getBLOBInfo(java.lang.Long id, java.lang.Long backuppingBPId) gathers information about the BLOB belonging to BO[i].
java.util.Iterator<java.lang.Long>	getExistingBLOBsIdIterator()
java.util.Iterator<java.lang.Long>	getExistingBLOBsIdIterator(java.util.Set<java.lang.Long> pendingBLOBChangeBOIdsLocal)
java.util.Iterator<VFile>	getExistingBLOBsVFileIterator(java.util.Set<java.lang.Long> pendingBLOBChangeBOIdsLocal) Traverses the storageDir and creates a Map with the ids and the VFile (with metadata about the file).
ManagedFileI	getHandle(java.io.InputStream is, java.lang.Long id) Returns a ManagedFileI for reading binary data from the given InputStream and storing it as BLOB of the BO with the passed Id
ManagedFileI	getHandle(java.io.InputStream is, java.lang.Long id, boolean noHistory)
ManagedFileI	getHandleForPullDuringSync(BLOBLoaderI blobLoader, long len, java.lang.String blobHash, java.lang.Long boid, java.lang.Long backuppingBPId, boolean noHistory)
ManagedFileI	getHandleForPushDuringSync(java.lang.Long id, boolean deletion, java.lang.Long backuppingBPId, java.lang.String blobHash)
ManagedFileI	getHandleForReceivingBLOBOnServerSide(java.io.ObjectInput in, long len, java.lang.String blobHash, java.lang.Long id, boolean syncMode, boolean noHistory)
ManagedFileI	getHandleForRemoveBLOB(java.lang.String oldHash, java.lang.Long id)
ManagedFileI	getHandleForRemoveBLOB(java.lang.String oldHash, java.lang.Long id, boolean noHistory)
ManagedFileI	getHandleForUndoBLOBChangeOnServerSide(java.lang.String oldHash, java.lang.String newHash, java.lang.Long undoBPId, java.lang.Long id, boolean noHistory)
static ServerFileVault	getInstance(DBManLocalI _dbm, netrexx.lang.Rexx _section) Returns the singleton instance of ServerFileVault, configuring it via a database manager's configuration.
static ServerFileVault	getInstance(DBManLocalI _dbm, netrexx.lang.Rexx _section, java.lang.String _legacyFilesRootName)
static ServerFileVault	getInstance(java.io.File _newFilesDir, java.io.File _storageDir, java.io.File _backupDir, java.io.File _lostAndFoundDir, java.io.File _atticDir) Deprecated. use the configuration-based factory method getInstance(DBManLocalI, Rexx, String) instead
InputStreamWrapper	getStream(java.lang.Long id) get the BLOB belonging to BO[id].
InputStreamWrapper	getStream(java.lang.Long id, java.lang.Long backuppingBPId) get the BLOB belonging to BO[id].
void	recover() Executes the recovery process for transactional file changes.
void	retireOrphanedBLOBsEventually(java.util.Set<java.lang.Long> blobIds) Initiates the eventual retirement (deletion) of BLOBs that are no longer referenced by the database.
VFile	storeRemoteBLOB(BLOBInputI in, java.lang.String newBLOBIdString, VFile rvfile, int current, int totalBLOBs)
long	toDataOutput(java.lang.Long boid, java.io.DataOutput oo, boolean closeOS, java.lang.Long backuppingBPId) Writes the BLOB belonging to BO[id] to the passed DataOutput.
long	toStream(java.lang.Long boid, java.io.OutputStream os, boolean closeOS, java.lang.Long backuppingBPId) Writes the BLOB belonging to BO[id] to the passed OutputStream.

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.ipcon.db.blob.ServerFileVaultI

exists, exists

Field Detail

log

public static final org.apache.log4j.Logger log

FILEEXTENSION_LOG

public static final java.lang.String FILEEXTENSION_LOG

See Also:

Constant Field Values

FILEEXTENSION_BLOB

public static final java.lang.String FILEEXTENSION_BLOB

See Also:

Constant Field Values

Constructor Detail

ServerFileVault

public ServerFileVault(java.io.File _newFilesDir,
                       java.io.File _storageDir,
                       java.io.File _backupDir,
                       java.io.File _lostAndFoundDir,
                       java.io.File _atticDir)

Private constructor for the ServerFileVault singleton.

This constructor initializes the paths for all managed directories and performs critical checks to ensure transactional integrity. Specifically, it verifies that the file system supports atomic move operations between the core directories, which is essential for guaranteeing that file transfers are completed or fully rolled back.

Parameters:

_newFilesDir - The temporary directory for incoming files.

_storageDir - The directory for live, committed files.

_backupDir - The directory for files being backed up before being replaced or deleted.

_lostAndFoundDir - The directory for files that were unassociated upon server start.

_atticDir - The directory for files moved out of primary storage because they are orphaned.

_dbm - The associated database manager instance (optional, may be null).

Throws:

java.lang.IllegalArgumentException - If atomic move operations are not supported between critical directories.

ServerFileVault

public ServerFileVault(java.io.File _newFilesDir,
                       java.io.File _storageDir,
                       java.io.File _backupDir,
                       java.io.File _lostAndFoundDir,
                       java.io.File _atticDir,
                       DBManLocalI _dbm)

Method Detail

getInstance

@Deprecated
public static ServerFileVault getInstance(java.io.File _newFilesDir,
                                                      java.io.File _storageDir,
                                                      java.io.File _backupDir,
                                                      java.io.File _lostAndFoundDir,
                                                      java.io.File _atticDir)

Deprecated. use the configuration-based factory method getInstance(DBManLocalI, Rexx, String) instead

Returns the singleton instance of ServerFileVault.

This factory method initializes the singleton with explicitly provided directory File objects. The configuration-based factory method (getInstance(DBManLocalI, Rexx, String)) is the primary path.

Parameters:

_newFilesDir - The directory for new, temporary files before they are committed.

_storageDir - The main, live storage directory for committed BLOBs.

_backupDir - The directory used to hold old BLOB versions after they were deleted or replaced by a new file.

_lostAndFoundDir - The directory for transaction control file remnants that were encountered upon server start.

_atticDir - The directory for files that are moved out of the main storage because they are orphaned.

Returns:

The singleton instance of ServerFileVault.

getInstance

public static ServerFileVault getInstance(DBManLocalI _dbm,
                                          netrexx.lang.Rexx _section)

Returns the singleton instance of ServerFileVault, configuring it via a database manager's configuration.

This is the primary factory method, typically called via reflection from DBMan#initFileVault(). It retrieves directory names from the DBManLocalI's configuration using a specified section and provides robust fallback logic for directory setup, including legacy support.

Parameters:

_dbm - The local database manager instance to retrieve the configuration from.

_section - The configuration section (Rexx object) where the directory paths are defined.

_legacyFilesRootName - An optional fallback directory name for legacy support if 'storageDir' is not configured. Can be null.

Returns:

The singleton instance of ServerFileVault.

Throws:

java.lang.IllegalArgumentException - If no 'storageDir' is configured and no legacy fallback name is provided.

getInstance

public static ServerFileVault getInstance(DBManLocalI _dbm,
                                          netrexx.lang.Rexx _section,
                                          java.lang.String _legacyFilesRootName)

retireOrphanedBLOBsEventually

public void retireOrphanedBLOBsEventually(java.util.Set<java.lang.Long> blobIds)

Initiates the eventual retirement (deletion) of BLOBs that are no longer referenced by the database.

This method is typically called as part of a scheduled integrity check or cleanup process (e.g. by the OrphanedBLOBsChecker). It identifies a batch of unreferenced files by their IDs and queues them for safe deletion. The process is "eventual" to decouple the integrity check from the potentially time-consuming file I/O operations.

Specified by:

retireOrphanedBLOBsEventually in interface IntegrityCheckingServerFileVaultI

Parameters:

blobIds - A Set of unique Long IDs corresponding to the BLOB files that are confirmed to be orphaned.

recover

public void recover()
             throws java.io.IOException

Executes the recovery process for transactional file changes.

This process examines the log files in the ServerFileVault directories to identify transactions that were committed in the database but failed to fully complete their corresponding file system operations (or vice-versa). It then attempts to complete the file system changes to restore transactional consistency.

Specified by:

recover in interface ServerFileVaultI

Throws:

IOException - If a severe I/O error occurs during the recovery process.

java.lang.IllegalStateException - If called before the persistence framework is fully initialized, as it requires querying Business Procedures (BP) and Business Objects (BO).

getBLOBInfo

public VFile getBLOBInfo(java.lang.Long id)

Description copied from interface: ServerFileVaultI

gathers information about the BLOB belonging to BO[i].

Specified by:

getBLOBInfo in interface ServerFileVaultI

Parameters:

id - the id of the BO the BLOB-info belongs to.

Returns:

VFile object containing information about lastmodification and size.

getBLOBInfo

public VFile getBLOBInfo(java.lang.Long id,
                         java.lang.Long backuppingBPId)

Description copied from interface: ServerFileVaultI

gathers information about the BLOB belonging to BO[i].

Specified by:

getBLOBInfo in interface ServerFileVaultI

Parameters:

id - the id of the BO the BLOB-info belongs to.

backuppingBPId - the information should be taken from the backup-BLOB in the backup-dir using this BP-Id

Returns:

VFile object containing information about lastmodification and size.

getStream

public InputStreamWrapper getStream(java.lang.Long id)

Description copied from interface: ServerFileVaultI

get the BLOB belonging to BO[id]. Gives back an InputStreamWrapper of the BLOB.

Specified by:

getStream in interface ServerFileVaultI

Parameters:

id - the id of the BO the BLOB belongs to.

Returns:

an InputStreamWrapper containing the data of the BLOB.

getStream

public InputStreamWrapper getStream(java.lang.Long id,
                                    java.lang.Long backuppingBPId)

Description copied from interface: ServerFileVaultI

get the BLOB belonging to BO[id]. Gives back an InputStreamWrapper of the BLOB.

Specified by:

getStream in interface ServerFileVaultI

Parameters:

id - the id of the BO the BLOB belongs to.

backuppingBPId - the data should be taken from the backup-BLOB in the backup-dir using this BP-Id

Returns:

an InputStreamWrapper containing the data of the BLOB.

toStream

public long toStream(java.lang.Long boid,
                     java.io.OutputStream os,
                     boolean closeOS,
                     java.lang.Long backuppingBPId)
              throws java.io.IOException

Description copied from interface: ServerFileVaultI

Writes the BLOB belonging to BO[id] to the passed OutputStream. writes to te given OutputStream

Specified by:

toStream in interface ServerFileVaultI

Parameters:

boid - the id of the BO the BLOB belongs to

os - the OutputStream to write the BLOB-bytes to

closeOS - a boolean designating if the OutputStream shall be closed afterwards or not.

backuppingBPId - the data should be taken from the backup-BLOB in the backup-dir using this BP-Id

Throws:

java.io.IOException

toDataOutput

public long toDataOutput(java.lang.Long boid,
                         java.io.DataOutput oo,
                         boolean closeOS,
                         java.lang.Long backuppingBPId)
                  throws java.io.IOException

Description copied from interface: ServerFileVaultI

Writes the BLOB belonging to BO[id] to the passed DataOutput. writes to te given DataOutput

Specified by:

toDataOutput in interface ServerFileVaultI

Parameters:

boid - the id of the BO the BLOB belongs to

oo - the DataOutput to write the BLOB-bytes to

closeOS - a boolean designating if the DataOutput shall be closed afterwards or not.

backuppingBPId - the BLOB should be taken from the backup-dir using this BP-Id

Throws:

java.io.IOException

getBLOB

public java.io.File getBLOB(java.lang.Long boid)

Description copied from interface: ServerFileVaultI

get the BLOB belonging to BO[id]. Gives back a File.

Specified by:

getBLOB in interface ServerFileVaultI

Parameters:

boid - the id of the BO the BLOB belongs to.

Returns:

a File handle pointing to a file containing the data of the BLOB.

getBLOB

public java.io.File getBLOB(java.lang.Long boid,
                            java.lang.Long backuppingBPId)

Description copied from interface: ServerFileVaultI

get the BLOB belonging to BO[id]. Gives back a File.

Specified by:

getBLOB in interface ServerFileVaultI

Parameters:

boid - the id of the BO the BLOB belongs to.

backuppingBPId - the BLOB should be taken from the backup-dir using this BP-Id

Returns:

a File handle pointing to a file containing the data of the BLOB.

getBackupFileName

public java.lang.String getBackupFileName(java.lang.Long boid,
                                          java.lang.Long bpid)

getBackupFileNameTemp

public java.lang.String getBackupFileNameTemp(java.lang.Long boid,
                                              java.lang.Long bpid)

getHandleForRemoveBLOB

public ManagedFileI getHandleForRemoveBLOB(java.lang.String oldHash,
                                           java.lang.Long id)

Specified by:

getHandleForRemoveBLOB in interface FileVaultI

getHandleForRemoveBLOB

public ManagedFileI getHandleForRemoveBLOB(java.lang.String oldHash,
                                           java.lang.Long id,
                                           boolean noHistory)

Specified by:

getHandleForRemoveBLOB in interface ServerFileVaultI

getHandle

public ManagedFileI getHandle(java.io.InputStream is,
                              java.lang.Long id)
                       throws java.io.IOException

Returns a ManagedFileI for reading binary data from the given InputStream and storing it as BLOB of the BO with the passed Id

Specified by:

getHandle in interface FileVaultI

Throws:

java.io.IOException

getHandle

public ManagedFileI getHandle(java.io.InputStream is,
                              java.lang.Long id,
                              boolean noHistory)
                       throws java.io.IOException

Specified by:

getHandle in interface ServerFileVaultI

Throws:

java.io.IOException

getHandleForReceivingBLOBOnServerSide

public ManagedFileI getHandleForReceivingBLOBOnServerSide(java.io.ObjectInput in,
                                                          long len,
                                                          java.lang.String blobHash,
                                                          java.lang.Long id,
                                                          boolean syncMode,
                                                          boolean noHistory)
                                                   throws java.io.IOException

Specified by:

getHandleForReceivingBLOBOnServerSide in interface FileVaultI

Throws:

java.io.IOException

getHandleForUndoBLOBChangeOnServerSide

public ManagedFileI getHandleForUndoBLOBChangeOnServerSide(java.lang.String oldHash,
                                                           java.lang.String newHash,
                                                           java.lang.Long undoBPId,
                                                           java.lang.Long id,
                                                           boolean noHistory)

Specified by:

getHandleForUndoBLOBChangeOnServerSide in interface FileVaultI

getHandleForPullDuringSync

public ManagedFileI getHandleForPullDuringSync(BLOBLoaderI blobLoader,
                                               long len,
                                               java.lang.String blobHash,
                                               java.lang.Long boid,
                                               java.lang.Long backuppingBPId,
                                               boolean noHistory)
                                        throws java.io.IOException

Specified by:

getHandleForPullDuringSync in interface ServerFileVaultI

Throws:

java.io.IOException

getHandleForPushDuringSync

public ManagedFileI getHandleForPushDuringSync(java.lang.Long id,
                                               boolean deletion,
                                               java.lang.Long backuppingBPId,
                                               java.lang.String blobHash)

Specified by:

getHandleForPushDuringSync in interface ServerFileVaultI

storeRemoteBLOB

public VFile storeRemoteBLOB(BLOBInputI in,
                             java.lang.String newBLOBIdString,
                             VFile rvfile,
                             int current,
                             int totalBLOBs)
                      throws java.io.FileNotFoundException

Specified by:

storeRemoteBLOB in interface ServerFileVaultI

Throws:

java.io.FileNotFoundException

getExistingBLOBsVFileIterator

public java.util.Iterator<VFile> getExistingBLOBsVFileIterator(java.util.Set<java.lang.Long> pendingBLOBChangeBOIdsLocal)
                                                        throws java.io.IOException

Traverses the storageDir and creates a Map with the ids and the VFile (with metadata about the file). This method is called on the sending end of command CMD_COPYBLOBS to determine which BLOBs exist locally.

Specified by:

getExistingBLOBsVFileIterator in interface ServerFileVaultI

Returns:

a Map with the ids and the VFile (with metadata about the file) for all local BLOBs in the storageDir

Throws:

java.io.IOException

getExistingBLOBsIdIterator

public java.util.Iterator<java.lang.Long> getExistingBLOBsIdIterator(java.util.Set<java.lang.Long> pendingBLOBChangeBOIdsLocal)
                                                              throws java.io.IOException

Specified by:

getExistingBLOBsIdIterator in interface ServerFileVaultI

Throws:

java.io.IOException

getExistingBLOBsIdIterator

public java.util.Iterator<java.lang.Long> getExistingBLOBsIdIterator()
                                                              throws java.io.IOException

Specified by:

getExistingBLOBsIdIterator in interface IntegrityCheckingServerFileVaultI

Throws:

java.io.IOException

getBLOBBOIdsForIntitialBLOBCopy

public InitialBLOBTransferMetaDataContainer getBLOBBOIdsForIntitialBLOBCopy(java.util.Map idsAndVFilesOnSyncNode,
                                                                            java.util.List pendingBLOBChangeBOIdsOnSyncNode,
                                                                            java.util.List pendingBLOBChangeBOIdsOnAuthNode)
                                                                     throws java.io.IOException

Returns the Ids of all local BLOBs, unless they are older or have the same hash as listed in the passed Map This method is called on the receiving end of command CMD_COPYBLOBS to determine which BLOBs exist locally, that do not exist on the sender's end or have a different hash.

Specified by:

getBLOBBOIdsForIntitialBLOBCopy in interface ServerFileVaultI

Returns:

a Map containing info about all local BLOBs, which are not part of idsAndVFilesOnSyncNode or have a different hash than on the remote end.

Throws:

java.io.IOException