Use the Data Load Tool to import and export class instance data and model structures to and from a relational database.

With the Data Load Tool, you can create any of the tables needed to begin developing against your models.

Data sources

A data source is a logical representation of physical storage that is used to create, read, update, and delete object instances.

Persistence mapping specifies how class instances will be persisted in a given data source.
The NexJ Framework supports the following types of data sources:

RelationalDatabase

Persists instances in a relational database.

FileStorage

Persists instances in a file system.

XML

Persists instances in an XML file.

Service

Persists instances using a collection of services such as web services or store procedures.

Composite

Provides a dynamic choice of possible alternative mappings at run time.

Data sources are configured and bound to physical storage addresses using connection. Data sources support a CRUD interface for interaction with external systems, whereas channels support a send/receive interface. The persistence interface for data sources is synchronous. In NexJ Studio, data sources appear as a tab in the Persistence layer of the model navigator.

Modifying database data

You use the Data Load Tool primarily to load new class instance data and model structures to your model.

The tool allows you to modify your model's databases using its import, upgrade, recreate, recreateschema, and reset commands.

Upgrading databases

Model-specific upgrade files contain one or more upgrades, which are associated with a version of the model.

Each upgrade contains steps that explicitly define the data store changes that are required to move from supporting a previous version of the model to supporting the version associated with the upgrade. Once you define an upgrade file for the current version of a model, it can be used to alter the structure or attributes of a database to fit with the current model version.

You can use the upgrade command to use the upgrade file to migrate the data store for any previous version of the model to the current version.

Before upgrading a database, make sure you have updated your model's upgrade file.

To upgrade a database:

1. In NexJ Studio, click the arrow next to the Run Tool button  and select Data Load Tool.
   The Data Load Tool opens.
2. In the Model section, select the model you want to use:
   • For the currently loaded model, shown in the label, select Current.
   • For a base model in your Model Library, select Base Model and select one of the available models from the drop-down.
   • For a previously published model in your file system, select Published Model JAR and click the Browse button  to locate the published model.
3. If you want to use a test environment, select the Test checkbox.

4. Specify the server and connections that you want the application to support when running with this database.

   Info

   If you are using the current model, then the fields allow you to select from among the environment, server, and connection files within the model. If you are using a base or published model, then your choice is limited to only those server and connection files contained in your global environment folder.

   1. In the Server field, specify either the server or environment file that contains the server configuration information you want to use when upgrading the database. If you specify an environment file, then it will also include the connections information.

      You must choose an environment or server file that uses IDs with permissions to change the database table structure, such as DBAdmin. This is necessary because the upgrade command overwrites existing databases

   2. In the Connections field, specify the connections file that you want to use when upgrading the database. If you previously selected an environment file in the Server field, then it already has the connections information, and this field becomes inactive.
5. In the Command field, select upgrade.
6. In the Data Source field, select the desired data source. Selections are limited to the model's relational data sources.
7. Click Run.
8. If using a non-test environment, a dialog opens, asking you to confirm that you want to overwrite the data. After confirming that it is acceptable to do so, select the checkbox and click OK.
9. [Optional] Publish the model from the Model Library. Publishing the new version before making any other changes creates a reference version for future upgrades. It also ensures that you have a backup working model if future changes make the model unusable.

Verifying the upgrade

To verify that the upgrade worked after running the script, run your database's management tool or query client.

Verify that the version record in the Version table matches the version of your model.

• In Microsoft SQL Server or DB2, issue the following statement to return the value of the version record in the Version table:

  select version from NJVersion

• In MySQL, issue the following statement to return the value of the version record in the Version table:

  use <modelName>;
  select version from NJVersion;

  where <modelName> is your model's name.

Recreating databases

Use the Data Load Tool's recreate or recreateschema command to drop and recreate all tables in the database associated with the environment. Use the recreate command to import the data after recreating all tables.

The recreate or recreateschema commands drop all tables defined in the selected datasource. The process then creates new tables based on the current model's datasource definitions. This method differs from the reset command in that a recreated database will always contain correctly structured tables for the current model.

Differences between recreate, recreateschema, and reset commands

To recreate a database:

1. In NexJ Studio, click the arrow next to the Run Tool button  and select Data Load Tool.
   The Data Load Tool opens.
2. In the Model section, select the model you want to use:
   • For the currently loaded model, shown in the label, select Current.
   • For a base model in your Model Library, select Base Model and select one of the available models from the drop-down list.
   • For a previously published model in your file system, select Published Model JAR and click the Browse button  to locate the published model. You might be prompted to specify the directory where the published model's mixins are located.
3. Select the Test checkbox if you want to use a test environment.
4. Specify the server and connections that you want the application to support when running with this database.
   1. In the Server field, specify either the server or environment file that contains the server configuration information you want to use when recreating the database. If you specify an environment file, then it will also include the connections information.

   2. In the Connections field, specify the connections file that you want to use when recreating the database. If you previously selected an environment file in the Server field, then it already has the connections information, and this field becomes inactive.
      

      Info

      You must choose an environment or connections file that uses IDs with the appropriate permissions to change the database table structure, such as the db_owner fixed database role in SQL Server. This is necessary because the recreate command and the recreateschema command overwrite existing databases.

      If you are using the current model, then the fields allow you to select from among the environment, server, and connections files within the model. If you are using a base or published model, then your choice is limited only to the environment, server, and connections files contained in your global environment folder.

5. In the Command field, select recreate or recreateschema.
6. In the Data Source field, select the desired data source.
   Selections are limited to the data source connections included in the environment or connections files for the model.
7. Click Run.
8. If using a non-test environment, a dialog opens, asking you to confirm that you want to overwrite the data. After confirming that it is acceptable to do so, select the checkbox and click OK.
9. [Optional] Publish the model from the Model Library. Publishing the new version before making any other changes creates a reference version for future upgrades. It also ensures that you have a backup working model if future changes make the model unusable.

Resetting databases

Use the reset command to truncate all tables in the database associated with the environment and import the specified dump file data.

The reset command truncates tables by systematically traversing the selected datasource and deleting the data from each table. This method differs from the recreate and recreateschema commands in that it maintains model structure. If any tables or classes have been physically changed, the reset will fail because it will attempt to import an outdated model structure.

To reset a database:

1. In NexJ Studio, click the arrow next to the Run Tool button  and select Data Load Tool.
   The Data Load Tool opens.
2. In the Model section, select the model you want to use:
   • For the currently loaded model, shown in the label, select Current.
   • For a base model in your Model Library, select Base Model and select one of the available models from the drop-down.
   • For a previously published model in your file system, select Published Model JAR and click the Browse button  to locate the published model.

3. Select the Test checkbox if you want to use a test environment.
   Specify the server and connections that you want the application to support when running with this database.

   Info

   If you are using the current model, then the fields allow you to select from among the environment, server, and connection files within the model. If you are using a base or published model, then your choice is limited to only those server and connection files contained in your global environment folder.

   1. In the Server field, specify either the server or environment file that contains the server configuration information you want to use when resetting the database. If you specify an environment file, then it will also include the connections information.

      Info

      You must choose an environment or server file that uses IDs with the appropriate permissions to change the database table structure, such as DBAdmin. This is necessary because theresetcommand overwrites existing databases.

   2. In the Connections field, specify the connections file that you want to use when resetting the database. If you previously selected an environment file in the Server field, then it already has the connections information, and this field becomes inactive.
4. In the Command field, select reset.
5. In the Data Source field, select the desired data source. Selections are limited to the model's relational data sources.
6. Click Run.
7. If using a non-test environment, a dialog opens, asking you to confirm that you want to overwrite the data. After confirming that it is acceptable to do so, select the checkbox and click OK.
8. [Optional] Publish the model from the Model Library. Publishing the new version before making any other changes creates a reference version for future upgrades. It also ensures that you have a backup working model if future changes make the model unusable.

Printing the current model version in the system

To print the current model version:

1. In NexJ Studio, click the arrow next to the Run Tool button  and select Data Load Tool.
   The Data Load Tool dialog opens.
2. In the Model section, select Current.
3. In the Server field, specify either the server or environment file that contains the server configuration information for the current model.
   If you specify an environment file, then it will also include the connections information.
4. In the Connections field, specify the appropriate connections file for the current model. If you previously selected an environment file in the Server field, then it already has the connections information, and this field becomes inactive.
5. In the Command field, select version and leave the other fields blank.
6. Click Run.
   The current model version is printed to the console.

The final three lines should be in the following format:

; <systemTime> INFO [MetadataLoaderDispatcher] Completed loading metadata from 
 "file:/<modelPath>"
<modelNamespace>#<versionNumber>
; <systemTime> INFO [GenericTool] Exit code = 0

where:

• <systemTime> is your system time when the output is completed.
• <modelPath> is the current model's file path.
• <modelNamespace> is the current model's namespace.
• <versionNumber> is the current model's version number.

For example, in the following output, the model version is 5.18:

; 16:23:32,919 INFO [MetadataLoaderDispatcher] Completed loading metadata from
"file:/C:/work/WS/training-101/meta/"
http://www.nexj.com/ns/training101#5.18
; 16:23:33,415 INFO [GenericTool] Exit code = 0

Setting virtual machine requirements

The Data Load Tool also allows you to set virtual machine (VM) requirements.

These can alter parameters such as allocation of memory or boot state of the machine.

The following are examples of two VM arguments you could use:

Ddump.format=JSON

Serializes to json rather than to the standard format.

Ddump.compressed=false

Specifies whether to use gzip or not. The default is true.

To set VM requirements:

1. Click Advanced in the Data Load Tool to open the VM Arguments field.
2. Enter your VM arguments in the VM Arguments field.