Package org.opensaml.core.xml.persist

# Class FilesystemLoadSaveManager<T extends XMLObject>

java.lang.Object
org.opensaml.core.xml.persist.AbstractConditionalLoadXMLObjectLoadSaveManager<T>
org.opensaml.core.xml.persist.FilesystemLoadSaveManager<T>

Type Parameters:
  `T` - the specific base XML object type being managed

All Implemented Interfaces:
  `ConditionalLoadXMLObjectLoadSaveManager<T>`, `XMLObjectLoadSaveManager<T>`

@NotThreadSafe public class FilesystemLoadSaveManager<T extends XMLObject> extends AbstractConditionalLoadXMLObjectLoadSaveManager<T>
Implementation of `XMLObjectLoadSaveManager` which uses a local filesystem to load and store serialized XML.

The primary required configuration is a base directory path under which files of serialized XML will be located. The file name to use is simply the specified String index key, which is treated as an immediate child file name of the base directory. Callers are required to ensure that index keys are acceptable as file names on the platform(s) on which this manager is used.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`private class`
`FilesystemLoadSaveManager.FileIterable`
Iterable which provides lazy iteration over the managed files.
`private class`
`FilesystemLoadSaveManager.FileIterator`
Iterator which provides lazy iteration over the managed files.

## Field Summary

Fields
Modifier and Type
Field
Description
`private File`
`baseDirectory`
The base directory used for storing individual serialized XML files.
`private Function<String,List<String>>`
`intermediateDirectoryStrategy`
Optional strategy function which produces the intermediate directory path(s) between the `baseDirectory` and the actual file.
`private org.slf4j.Logger`
`log`
Logger.
`private ParserPool`
`parserPool`
Parser pool instance for deserializing XML from the filesystem.

## Constructor Summary

Constructors
Constructor
Description
`FilesystemLoadSaveManager(File baseDir)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, boolean conditionalLoad)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, boolean conditionalLoad, Function<String,List<String>> dirStrategy)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, Function<String,List<String>> dirStrategy)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, ParserPool pp)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, ParserPool pp, boolean conditionalLoad)`
Constructor.
`FilesystemLoadSaveManager(File baseDir, ParserPool pp, boolean conditionalLoad, Function<String,List<String>> dirStrategy)`
Constructor.
`FilesystemLoadSaveManager(String baseDir)`
Constructor.
`FilesystemLoadSaveManager(String baseDir, boolean conditionalLoad)`
Constructor.
`FilesystemLoadSaveManager(String baseDir, ParserPool pp)`
Constructor.
`FilesystemLoadSaveManager(String baseDir, ParserPool pp, boolean conditionalLoad)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`File`
`buildFile(String key)`
Build the target file name from the specified index key and the configured base directory.
`protected void`
`checkAndCreateIntermediateDirectories(File file)`
Check and create intermediate directories between the `baseDirectory` and the actual file, if necessary.
`boolean`
`exists(String key)`
Evaluate whether an object already exists indexed by the supplied key.
`protected boolean`
`isUnmodifiedSinceLastLoad(String key)`
Check whether the data corresponding to the specified key has been modified since the last time `XMLObjectLoadSaveManager.load(String)` was called for that key.
`Iterable<Pair<String,T>>`
`listAll()`
Return an iterable of all objects under management, along with their associated index key.
`Set<String>`
`listKeys()`
Return a set of the index keys of all objects under management.
`T`
`load(String key)`
Load a particular object based on the supplied key.
`boolean`
`remove(String key)`
Remove the object indexed by the specified key.
`void`
`save(String key, T xmlObject)`
Save a particular object, indexed by the supplied key.
`void`
`save(String key, T xmlObject, boolean overwrite)`
Save a particular object, indexed by the supplied key.
`boolean`
`updateKey(String currentKey, String newKey)`
Update the key under which a particular object is stored.

### Methods inherited from class org.opensaml.core.xml.persist.AbstractConditionalLoadXMLObjectLoadSaveManager

`clearAllLoadLastModified, clearLoadLastModified, getLoadLastModified, isLoadConditionally, updateLoadLastModified, updateLoadLastModified`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### log

@Nonnull private org.slf4j.Logger log
Logger.

### baseDirectory

@Nonnull private File baseDirectory
The base directory used for storing individual serialized XML files.

### intermediateDirectoryStrategy

@Nullable private Function<String,List<String>> intermediateDirectoryStrategy
Optional strategy function which produces the intermediate directory path(s) between the `baseDirectory` and the actual file.

### parserPool

@Nonnull private ParserPool parserPool
Parser pool instance for deserializing XML from the filesystem.

## Constructor Details

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDir") @Nonnull String baseDir)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDir") @Nonnull String baseDir, @ParameterName(name="conditionalLoad") boolean conditionalLoad)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="intermediateDirectoryStrategy") @Nullable Function<String,List<String>> dirStrategy)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `dirStrategy` - the intermediate directory strategy

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="conditionalLoad") boolean conditionalLoad)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="conditionalLoad") boolean conditionalLoad, @ParameterName(name="intermediateDirectoryStrategy") @Nullable Function<String,List<String>> dirStrategy)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`
  `dirStrategy` - the intermediate directory strategy

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDir") @Nonnull String baseDir, @ParameterName(name="parserPool") @Nullable ParserPool pp)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `pp` - the parser pool instance to use

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDir") @Nonnull String baseDir, @ParameterName(name="parserPool") @Nullable ParserPool pp, @ParameterName(name="conditionalLoad") boolean conditionalLoad)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `pp` - the parser pool instance to use
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="parserPool") @Nullable ParserPool pp)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `pp` - the parser pool instance to use

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="parserPool") @Nullable ParserPool pp, @ParameterName(name="conditionalLoad") boolean conditionalLoad)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `pp` - the parser pool instance to use
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`

### FilesystemLoadSaveManager

public FilesystemLoadSaveManager(@ParameterName(name="baseDirFile") @Nonnull File baseDir, @ParameterName(name="parserPool") @Nullable ParserPool pp, @ParameterName(name="conditionalLoad") boolean conditionalLoad, @ParameterName(name="intermediateDirectoryStrategy") @Nullable Function<String,List<String>> dirStrategy)
Constructor.

Parameters:
  `baseDir` - the base directory, must be an absolute path
  `pp` - the parser pool instance to use
  `conditionalLoad` - whether `load(String)` should behave as defined in `ConditionalLoadXMLObjectLoadSaveManager`
  `dirStrategy` - the intermediate directory strategy

## Method Details

### listKeys

@Nonnull @NotLive @Unmodifiable public Set<String> listKeys() throws IOException
Return a set of the index keys of all objects under management.

Returns:
  a set of all indexed keys
Throws:
  `IOException` - if there is a fatal error obtaining the keys

### listAll

@Nonnull @NotLive @Unmodifiable public Iterable<Pair<String,T>> listAll() throws IOException
Return an iterable of all objects under management, along with their associated index key.

Returns:
  an iterable of all managed objects
Throws:
  `IOException` - if there is a fatal error loading the managed objects

### exists

public boolean exists(@Nonnull String key) throws IOException
Evaluate whether an object already exists indexed by the supplied key.

Parameters:
  `key` - the key of the desired object
Returns:
  true if object exists, false otherwise
Throws:
  `IOException` - if there is a fatal error evaluating object existence

### load

public T load(@Nonnull String key) throws IOException
Load a particular object based on the supplied key.

Parameters:
  `key` - the key of the desired object
Returns:
  the object saved under the specified key, or null if there is no such object
Throws:
  `IOException` - if there is a fatal error loading the object

### isUnmodifiedSinceLastLoad

protected boolean isUnmodifiedSinceLastLoad(@Nonnull String key) throws IOException
Check whether the data corresponding to the specified key has been modified since the last time `XMLObjectLoadSaveManager.load(String)` was called for that key.

Specified by:
  `isUnmodifiedSinceLastLoad` in class `AbstractConditionalLoadXMLObjectLoadSaveManager<T extends XMLObject>`
Parameters:
  `key` - the data key
Returns:
  true if the corresponding data has been modified since the last load, false otherwise
Throws:
  `IOException` - if there is a fatal error evaluating the last modified status

### save

public void save(@Nonnull String key, @Nonnull T xmlObject) throws IOException
Save a particular object, indexed by the supplied key.

An existing object indexed by the supplied key will not be overwritten. Instead an `IOException` will be thrown. For saving with the overwrite option, see `XMLObjectLoadSaveManager.save(String, XMLObject, boolean)`.

Parameters:
  `key` - the key under which to index the object
  `xmlObject` - the object to save
Throws:
  `IOException` - if there is a fatal error saving the object, or if an object already exists indexed by the supplied key

### save

public void save(@Nonnull String key, @Nonnull T xmlObject, boolean overwrite) throws IOException
Save a particular object, indexed by the supplied key.

Parameters:
  `key` - the key under which to index the object
  `xmlObject` - the object to save
  `overwrite` - whether or not to overwrite any existing object indexed by the supplied key
Throws:
  `IOException` - if there is a fatal error saving the object, or if overwrite=false, if an object already exists indexed by the supplied key

### remove

public boolean remove(@Nonnull String key) throws IOException
Remove the object indexed by the specified key.

Parameters:
  `key` - the key of the object to remove
Returns:
  true if the object was found and successfully removed, false if no such object was found
Throws:
  `IOException` - if there was a fatal error removing the object

### updateKey

public boolean updateKey(@Nonnull String currentKey, @Nonnull String newKey) throws IOException
Update the key under which a particular object is stored.

Parameters:
  `currentKey` - the current key under which the object is stored
  `newKey` - the new key under which the object should be stored
Returns:
  true if the object was found under the current key and the key successfully updated, false if no such object was found
Throws:
  `IOException` - if there was a fatal error updating the key

### checkAndCreateIntermediateDirectories

protected void checkAndCreateIntermediateDirectories(@Nonnull File file) throws IOException
Check and create intermediate directories between the `baseDirectory` and the actual file, if necessary.

Parameters:
  `file` - the target file whose path is to be evaluated
Throws:
  `IOException` - if the intermediate directory creation fails

### buildFile

@Nonnull public File buildFile(String key) throws IOException
Build the target file name from the specified index key and the configured base directory.

Parameters:
  `key` - the target file name index key
Returns:
  the constructed File instance for the target file
Throws:
  `IOException` - if there is a fatal error constructing or evaluating the candidate target path