public interface ImportMigrationEntry extends MigrationEntry
ImportMigrationEntry
interface provides support for artifacts that are being
imported during migration.
Entries retrieved via the import migration context or via the getPropertyReferencedEntry(java.lang.String)
methods are not restored back on disk. Storage of these entries is
controlled by the Migratable
using the restore()
methods. This allows the
migratable a chance to make additional checks if need be. In some cases, the migratable might not
be responsible for actually migrating the content of a file and might only be responsible for
migrating the file being referenced by a given property in it. This is the case, for example,
with Java properties file where a migratable might be responsible for migrating the file being
referenced from a property in a properties file but not the properties file itself. In such case,
the migratable would retrieve an entry for the properties file that holds the property in
question via the ImportMigrationContext.getEntry(java.nio.file.Path)
and then retrieve a migration entry for
the file referenced from one of its properties using the getPropertyReferencedEntry(java.lang.String)
method.
For example:
public class MyMigratable implements Migratable { ... public void doImport(ImportMigrationContext context) { // get an entry for my properties file final ImportMigrationEntry entry = context.getEntry(Paths.get("etc", "myfile.properties")); // get an entry for the file referenced from "my.properties" and restore it back on disk entry.getPropertyReferencedEntry("my.property") .ifPresent(ImportMigrationEntry::restore); } ... }
This code is experimental. While this interface is functional and tested, it may change or be removed in a future version of the library.
Modifier and Type | Method and Description |
---|---|
Optional<InputStream> |
getInputStream()
Gets an input stream for this entry.
|
Optional<ImportMigrationEntry> |
getPropertyReferencedEntry(String name)
Retrieves a migration entry referenced from a property value defined in the properties file
associated with this migration entry.
|
default boolean |
restore()
Restores this entry's content underneath the distribution root directory based on this entry's
path which can include sub-directories.
|
boolean |
restore(BiThrowingConsumer<MigrationReport,Optional<InputStream>,IOException> consumer)
Restores this required entry's content appropriately based on this entry's path which can
include sub-directories using the specified consumer.
|
boolean |
restore(boolean required)
Restores this entry's content underneath the distribution root directory based on this entry's
path which can include sub-directories.
|
boolean |
restore(boolean required,
PathMatcher filter)
Restores all entries that recursively match the provided path filter underneath the
distribution root directory based on this entry's path which can include sub-directories.
|
default boolean |
restore(PathMatcher filter)
Restores all files that recursively match the provided path filter underneath the distribution
root directory based on this entry's path which can include sub-directories.
|
getId, getLastModifiedTime, getName, getPath, getReport, isDirectory, isFile
compareTo
Optional<ImportMigrationEntry> getPropertyReferencedEntry(String name)
The entry returned would be an entry representing the file that was referenced by the specified property value in the java properties file represented by this entry on the exported system. For example:
If the properties file (e.g. etc/ws-security/server/encryption.properties) represented by this entry defined the following mapping: org.apache.ws.security.crypto.merlin.x509crl.file=etc/certs/demoCA/crl/crl.pem
then the following code:
final ImportMigrationEntry entry = context.getEntry("etc/ws-security/server/encryption.properties"); final Optional<ImportMigrationEntry> entry2 = entry.getPropertyReferenceEntry("org.apache.ws.security.crypto.merlin.x509crl.file");
would return an entry representing the exported file etc/certs/demoCA/crl/crl.pem
allowing the migratable a chance to restore it in its original location and verifying
that the property in the local etc/ws-security/server/encryption.properties file is still
defined with the same value after the import operation has completed.
name
- the name of the property that contains the reference to a migration entryname
in
the properties file referenced by this entry or empty if it was not exportedIllegalArgumentException
- if name
is null
default boolean restore()
This entry's sub-directories (if any) will be created if they don't already exist. The destination file will be overwritten if it already exists.
All errors and warnings are automatically recorded with the associated migration report.
Errors can be reported in two ways:
MigrationException
(e.g. failure to write to the exported file)
false
is returned from this method. This allows for the accumulation of as many issues
as possible to report to the user before aborting the operation.
Note: If this entry represents a directory which had been completely exported using
ExportMigrationEntry.store()
or ExportMigrationEntry.store(boolean)
then in
addition to restoring all entries recursively, calling this method will also remove any
existing files or directories that were not on the original system.
Note: Calling restore()
twice will not restore the entry two times. The
second time it is called, the same result will be returned as the first time no matter which
restore()
method was called.
true
if no errors were recorded as a result of processing this command;
false
otherwiseMigrationException
- if a failure that prevents the operation from continuing occurredSecurityException
- if a security manager exists and the file entry was exported by the
migratable directly using ExportMigrationEntry.store(BiThrowingConsumer)
or ExportMigrationEntry.getOutputStream()
) and its checkWrite()
method denies
write access or its checkDelete()
denies delete access to the file represented
by this entryboolean restore(boolean required)
This entry's sub-directories (if any) will be created if they don't already exist. The destination file will be overwritten if it already exists.
All errors and warnings are automatically recorded with the associated migration report.
Errors can be reported in two ways:
MigrationException
(e.g. failure to write to the exported file)
false
is returned from this method. This allows for the accumulation of as many issues
as possible to report to the user before aborting the operation.
Note: If this entry represents a directory which had been completely exported using
ExportMigrationEntry.store()
or ExportMigrationEntry.store(boolean)
then in
addition to restoring all entries recursively, calling this method will also remove any
existing files or directories that were not on the original system.
Note: Calling restore()
twice will not restore the entry two times. The
second time it is called, the same result will be returned as the first time no matter which
restore()
method was called.
required
- true
if the file or directory is required to exist in the export
and if it doesn't an error should be recorded; false
if the file or directory
is optional and may not be exported in which case calling this method will do nothingtrue
if no errors were recorded as a result of processing this command;
false
otherwiseMigrationException
- if a failure that prevents the operation from continuing occurredSecurityException
- if a security manager exists and the file entry was exported by the
migratable directly using ExportMigrationEntry.store(BiThrowingConsumer)
or ExportMigrationEntry.getOutputStream()
) and its checkWrite()
method denies
write access or its checkDelete()
denies delete access to the file represented
by this entrydefault boolean restore(PathMatcher filter)
true
will be returned.
This entry's sub-directories (if any) will be created if they don't already exist. The destination file will be overwritten if it already exists.
All errors and warnings are automatically recorded with the associated migration report.
Errors can be reported in two ways:
MigrationException
(e.g. failure to write to the exported file)
false
is returned from this method. This allows for the accumulation of as many issues
as possible to report to the user before aborting the operation.
Note: Calling restore()
twice will not restore the entry two times. The
second time it is called, the same result will be returned as the first time no matter which
restore()
method was called.
filter
- the path filter to usetrue
if no errors were recorded as a result of processing this command;
false
otherwiseIllegalArgumentException
- if filter
is null
MigrationException
- if a failure that prevents the operation from continuing occurredSecurityException
- if a security manager exists and the file entry was exported by the
migratable directly using ExportMigrationEntry.store(BiThrowingConsumer)
or ExportMigrationEntry.getOutputStream()
) and its checkWrite()
method denies
write access or its checkDelete()
denies delete access to the file represented
by this entryboolean restore(boolean required, PathMatcher filter)
required
parameter is interpreted for recording errors and deciding what to return.
This entry's sub-directories (if any) will be created if they don't already exist. The destination file will be overwritten if it already exists.
All errors and warnings are automatically recorded with the associated migration report.
Errors can be reported in two ways:
MigrationException
(e.g. failure to write to the exported file)
false
is returned from this method. This allows for the accumulation of as many issues
as possible to report to the user before aborting the operation.
Note: Calling restore()
twice will not restore the entry two times. The
second time it is called, the same result will be returned as the first time no matter which
restore()
method was called.
required
- true
if the file or directory is required to exist in the export
and if it doesn't an error should be recorded; false
if the file or directory
is optional and may not be exported in which case calling this method will do nothingfilter
- the path filter to usetrue
if no errors were recorded as a result of processing this command;
false
otherwiseIllegalArgumentException
- if filter
is null
MigrationException
- if a failure that prevents the operation from continuing occurredSecurityException
- if a security manager exists and the entry was exported by the
migratable directly using ExportMigrationEntry.store(BiThrowingConsumer)
or ExportMigrationEntry.getOutputStream()
) and its checkWrite()
method denies
write access or its checkDelete()
denies delete access to the file represented
by this entryboolean restore(BiThrowingConsumer<MigrationReport,Optional<InputStream>,IOException> consumer)
All errors and warnings are automatically recorded with the associated migration report including those thrown by the consumer logic.
Errors can be reported in two ways:
MigrationException
(e.g. failure to read from the exported file)
false
is returned from this method. This allows for the accumulation of as many issues
as possible to report to the user before aborting the operation.
Note: The input stream will automatically be closed (if not closed already) when the operation completes successfully or not.
consumer
- a consumer capable of importing the content of this entry from a provided input
stream which might be empty if the entry was not exported or if the entry represents a
directory (otherwise an error will automatically be recorded)true
if no errors were recorded as a result of processing this command;
false
otherwiseIllegalArgumentException
- if consumer
is null
MigrationException
- if a failure that prevents the operation from continuing occurredSecurityException
- if a security manager exists and the entry was exported by the
framework using ExportMigrationEntry.store()
or ExportMigrationEntry.store(boolean)
and its checkRead()
method denies read
access to the file represented by this entryOptional<InputStream> getInputStream() throws IOException
Note: The input stream provided will automatically be closed (if not closed already) regardless of whether or not the operation completes successfully for the associated migratable.
IOException
- if an I/O error has occurredSecurityException
- if a security manager exists and the entry was exported by the
framework using ExportMigrationEntry.store()
or ExportMigrationEntry.store(boolean)
and its checkRead()
method denies read
access to the file represented by this entryThis work is licensed under a Creative Commons Attribution 4.0 International License.