org.sandev.basics.structs
Class DataImportExportStruct

java.lang.Object
  org.sandev.basics.structs.DataImportExportStruct

Direct Known Subclasses:

DataImportExport

public class DataImportExportStruct
extends java.lang.Object

A transmittable directive for import/export actions used for system administration or similar purposes. A DataImportExport operation is intended for use in situations outside of the standard query processing mechanisms, where the usual user semantics do not apply. Like Ping, authorization should be granted with caution. Care should also be taken so that the result of an import/export action does not pose a security risk.

Sources of DataImportExport messages include administrative interfaces such as custom control panels. The DataManager is a typical receiver (if configured with a supporting Persister implementation), but targets may also include adaptor nodes with access to data sources.

A DataImportExport message is its own return value and is used solely for the side effects it produces. The return status and messages can be read from the SandTransmitMessage interface.

Notes on use:

When setting the dataDescriptions, be aware that if ChildStruct extends ParentStruct, and you provide a general ParentQuery and ChildQuery, then you may end up with duplicate instances of Child messages. One from when they were retrieved as a Parent, and one from when they were retrieved as a Child.

There are specific solutions to this, and it is possible for a Persister to handle this intelligently, but the needs of bulk data export are different than what is usually required for query processing, and it seems excessive to require this from a Persister implementation. Especially as most databases have their own backup processing which is far more efficient. In general, if you put a field in the parent class to indicate whether it's actually a child class, you break stuff about what inheritance means. If you try and tag things in the child, you run into problems with inheritance trees. This issue can't generally be solved well, but it can be solved in any specific application. Options:

1. Export only the child classes. With no parent classes queried, there are no duplicate entries produced. Whether this is possible in your application depends on your data model.
2. Use a marker field value in the parent. Only export parent classes with one group of values, and only export child classes with the remaining values.

The correct solution depends on your data model, application requirements, and underlying persistence technology.

This message can be transmitted directly outside of a verb form.
This message implements the AuthUser interface using email as the username.

Field Summary

protected int	action Whether this is an import or export operation.
protected SandQueryMessage[]	dataDescriptions A series of queries describing the data to be exported.
protected SandStructMessage	existingInstance In the event of an import failure due to conflicting instances this holds the existing instance.
protected SandStructMessage	importInstance In the event of an import failure due to conflicting instances this holds the import instance.
protected int	maxReturnOverride The value to use for maxReturn in the queries passed in the dataDescriptions field.
protected int	resolution Indicates the action which should occur in the event that the data being imported already exists and is different.
protected java.lang.String	source The import or export location.

Constructor Summary

DataImportExportStruct()

Method Summary

Methods inherited from class java.lang.Object

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

Field Detail

source

protected java.lang.String source

The import or export location. This could be a filename or some other specification as required by the receiver. Typically this is an xml filename, possibly prefixed with a relative path.

Length in characters, normal: 40 max: 128
help text: The import or export location. Normally an xml filename, possibly prefixed with a relative path.

action

protected int action

Whether this is an import or export operation.

declared default value: EXPORT

enumerated constant values:

• EXPORT("Export") = 0
  Indicates the data should be exported.
• IMPORT("Import") = 1
  Indicates the data should be imported.
• RESTORE("Restore") = 2
  Indicates the data should be imported, with the lastUpdateTime for each entry preserved.

"is" boolean methods are generated for this field.
help text: Whether this is an import or export operation.

dataDescriptions

protected SandQueryMessage[] dataDescriptions

A series of queries describing the data to be exported. On import this field is generally ignored, but may optionally be used to selectively pull only matching records from the import data.

help text: A series of queries describing the data to be exported. On import this field is generally ignored.

maxReturnOverride

protected int maxReturnOverride

The value to use for maxReturn in the queries passed in the dataDescriptions field. Queries are typically limited to the system defined maximum through the maxReturn field of the SandQueryMessage, which may be inadequate for a complete data export. For example if the system max is 200, then all the queries will have maxReturn set to 200. If there are more than 200 of anything you are trying to export, then export will fail.

To get around this export limit you can:

1. Limit the query. The most usual approach is to delete old data and then match on RECORDSTATUS_ACTIVE in each query.
2. Override the maxReturn value to increase the data retrieved.

Be aware that the maxReturn limit on queries is there for a reason. You can definitely load more data from the database than what will fit into memory, and that's what this override is allowing you to do.

The override is applied if its value is greater than zero.

help text: The value to use for maxReturn in the queries passed in the dataDescriptions field. Queries are typically limited to the

resolution

protected int resolution

Indicates the action which should occur in the event that the data being imported already exists and is different.

declared default value: ABORT

enumerated constant values:

• ABORT("Abort") = 0
  If an instance exists, and is different than the data we are importing, then abort the entire import operation and rollback any changes.
• OVERWRITE("Overwrite") = 1
  Overwrite any existing data with the the import data.
• MERGE("Merge") = 2
  If an instance exists, but is different than what is specified in the import data, then leave it alone. This assumes that the import data is older and should not cause changes to what is currently around. It is up to the application to ensure that the resulting import does not result in an inconsistent data state.
• FAIL("Fail") = 3
  If an instance exists, but is different than what is specified in the import data, then stop processing and return the two conflicting instances. The application can then choose to resolve the situation however it wants and presumably retry the import operation. This is essentially a manual merge.

"has" boolean methods are generated for this field.
help text: Indicates the action which should occur in the event that the data being imported already exists and is different.

existingInstance

protected SandStructMessage existingInstance

In the event of an import failure due to conflicting instances this holds the existing instance. This can be compared to the importInstance for resolution purposes.

help text: In the event of an import failure due to conflicting instances this holds the existing instance. This can be compared to the importInstance for resolution purposes.

importInstance

protected SandStructMessage importInstance

In the event of an import failure due to conflicting instances this holds the import instance. This can be compared to the existingInstance for resolution purposes.

help text: In the event of an import failure due to conflicting instances this holds the import instance. This can be compared to the existingInstance for resolution purposes.

Constructor Detail

DataImportExportStruct

public DataImportExportStruct()