public interface ExportMigrationEntry extends MigrationEntry
ExportMigrationEntry
interfaces provides support for artifacts that are being
exported during migration.
Entries created via the export migration context or via the getPropertyReferencedEntry(java.lang.String)
methods are not stored in the export file. Storage of these entries
is controlled by the Migratable
using the store()
methods. This gives 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. 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 create an entry for the properties file that holds the property in question via
the {link ExportMigrationContext#getEntry} and then create 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 doExport(ExportMigrationContext context) { // get an entry for my properties file final ExportMigrationEntry entry = context.getEntry(Paths.get("etc", "myfile.properties")); // get an entry for the file referenced from "my.properties" and store it in the export file entry.getPropertyReferencedEntry("my.property") .ifPresent(ExportMigrationEntry::store); } ... }
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 |
---|---|
OutputStream |
getOutputStream()
Gets an output stream for this entry which provides a low-level way for the migratable to store
its own content in the export.
|
default Optional<ExportMigrationEntry> |
getPropertyReferencedEntry(String name)
Creates or retrieves (if already created) a migration entry referenced from the specified
property in the properties file associated with this migration entry to be exported by the
corresponding migratable.
|
Optional<ExportMigrationEntry> |
getPropertyReferencedEntry(String name,
BiPredicate<MigrationReport,String> validator)
Creates or retrieves (if already created) a migration entry referenced from the specified
property in the properties file associated with this migration entry to be exported by the
corresponding migratable.
|
default boolean |
store()
Stores this entry's content in the export based on this entry's path which can include
sub-directories.
|
boolean |
store(BiThrowingConsumer<MigrationReport,OutputStream,IOException> consumer)
Stores this entry's content in the export using the specified consumer based on this entry's
path which can include sub-directories.
|
boolean |
store(boolean required)
Stores this entry's content in the export based on this entry's path which can include
sub-directories.
|
boolean |
store(boolean required,
PathMatcher filter)
Stores all files that recursively match the provided path filter in the export based on this
entry's path which can include sub-directories.
|
default boolean |
store(PathMatcher filter)
Stores all files that recursively match the provided path filter in the export based on this
entry's path which can include sub-directories.
|
getId, getLastModifiedTime, getName, getPath, getReport, isDirectory, isFile
compareTo
default Optional<ExportMigrationEntry> getPropertyReferencedEntry(String name)
An error will be automatically recorded with the associated migration report if the property is not defined in the property file referenced by this entry or its value is blank.
Note: The file referenced from the property is assumed to be relative to ${ddf.home} if not defined as absolute. All paths will automatically be relativized from ${ddf.home} if located underneath.
The entry returned would be an entry representing the file that is referenced by the specified property value in the java properties file represented by this entry on the local system. For example:
If the properties file (e.g. etc/ws-security/server/encryption.properties) represented by this entry defines the following mapping: org.apache.ws.security.crypto.merlin.x509crl.file=etc/certs/demoCA/crl/crl.pem
then the following code:
final ExportMigrationEntry entry = context.getEntry("etc/ws-security/server/encryption.properties"); final Optional<ExportMigrationEntry> entry2 = entry.getPropertyReferenceEntry("org.apache.ws.security.crypto.merlin.x509crl.file");
would return an entry representing the local file etc/certs/demoCA/crl/crl.pem
giving the migratable a chance to export it alongside the original property value so it can be
later restored and the property value can be verified after the import operation such that it
would still be defined with the same value in the local
etc/ws-security/server/encryption.properties file.
name
- the name of the property in the corresponding java properties file referencing a
migration entry to create or retrieveIllegalArgumentException
- if name
is null
Optional<ExportMigrationEntry> getPropertyReferencedEntry(String name, BiPredicate<MigrationReport,String> validator)
The provided predicate is always invoked (as long as the entry was not previously created)
to validate the property value which may be null
if not defined. Returning
false
will abort the process and yield an Optional.empty()
being returned out of
this method. In such case, it is up to the validator to record any required errors or warnings.
Returning true
from the predicate will allow for a new entry to be created for the
corresponding system property unless the property is not defined or its value is blank in which
case an error will be recorded and an Optional.empty()
is returned from this method. In
other words:
false
, no migration entry is created and no error
is recorded.
true
and ...
Note: The file referenced from the property is assumed to be relative to ${ddf.home} if not defined as absolute. All paths will automatically be relativized from ${ddf.home} if located underneath.
The entry returned would be an entry representing the file that is referenced by the specified property value in the java properties file represented by this entry on the local system. For example:
If the properties file (e.g. etc/ws-security/server/encryption.properties) represented by this entry defines the following mapping: org.apache.ws.security.crypto.merlin.x509crl.file=etc/certs/demoCA/crl/crl.pem
then the following code:
final ExportMigrationEntry entry = context.getEntry("etc/ws-security/server/encryption.properties"); final Optional<ExportMigrationEntry> entry2 = entry.getPropertyReferenceEntry("org.apache.ws.security.crypto.merlin.x509crl.file");
would return an entry representing the local file etc/certs/demoCA/crl/crl.pem
allowing the migratable a chance to export it alongside the original property value so it can
be later restored and the property value can be verified after the import operation such that
it would still be defined with the same value in the local
etc/ws-security/server/encryption.properties file.
name
- the name of the property in the corresponding java properties file referencing a
migration entry to create or retrievevalidator
- a predicate to be invoked to validate the property value further which must
return true
to have a migration entry createdIllegalArgumentException
- if name
or validator
is null
SecurityException
- if a security manager exists and its checkRead()
method
denies read access to the file represented by this entrydefault boolean store()
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 store()
twice will not store the entry twice. The second
time it is called, the same result will be returned as the first time no matter which
store()
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 occurredboolean store(boolean required)
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 store()
twice will not store the entry twice. The second
time it is called, the same result will be returned as the first time no matter which
store()
method was called.
required
- true
if the file or directory is required to exist on disk and if
it doesn't an error should be recorded; false
if the file or directory is
optional and may not be present 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 occurreddefault boolean store(PathMatcher filter)
true
will be
returned.
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 store()
twice will not store the entry twice. The second
time it is called, the same result will be returned as the first time no matter which
store()
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 occurredboolean store(boolean required, PathMatcher filter)
required
parameter is interpreted for recording errors
and deciding what to return.
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 store()
twice will not store the entry twice. The second
time it is called, the same result will be returned as the first time no matter which
store()
method was called.
required
- true
if the file or directory is required to exist on disk and if
it doesn't an error should be recorded; false
if the file or directory is
optional and may not be present 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 occurredboolean store(BiThrowingConsumer<MigrationReport,OutputStream,IOException> consumer)
All errors and warnings are automatically recorded with the associated migration report including those thrown by the consumer's logic.
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: The output stream will automatically be closed (if not closed already) when the
output stream for another entry is retrieved, when calling store()
on another entry, or
when the export operation completes regardless of outcome for the associated migratable.
Note: Calling store()
twice will not store the entry twice. The second
time it is called, the same result will be returned as the first time no matter which
store()
method was called.
Note: Storing an entry in this fashion will automatically mark the entry as a file even though on disk it might have represented a directory.
consumer
- a consumer capable of exporting the content of this entry to a provided output
streamtrue
if no errors were recorded as a result of processing this command;
false
otherwiseMigrationException
- if a failure that prevents the operation from continuing occurredIllegalArgumentException
- if consumer
is null
OutputStream getOutputStream() throws IOException
Note: The output stream will automatically be closed (if not closed already) wwhen
the output stream for another entry is retrieved, when calling store()
on another entry,
or when the export operation completes regardless of outcome for the associated migratable.
Note: Storing an entry via the output stream returned by this method will automatically mark the entry as a file even though on disk it might have represented a directory.
IOException
- if an I/O error has occurredThis work is licensed under a Creative Commons Attribution 4.0 International License.