NovaFACTORY Java Connector

The novaFACTORY for Java Library (NF4J) lets you communicate with your novaFACTORY (nF) server instance. It allows you to load and store CityGML with the help of your nF instance using nF's HTTP servlet interface. NF4J is essentially a Java wrapper which hides and processes HTTP requests and responses. In turn, NF4J provides a convenient API for SimStadt programmers.

Usage

The API described in the next two sections has been implemented against novaFACTORY version 6.3.1.1. If your installation has a different version, the API operations are likly to fail.

Export Jobs

In order to load a CityGML model you have to send an export job to the nF server. Before a job can be sent, you have to describe what you want to load. Every export job has an export job description. Export job descriptions let you select the data to be loaded, how to perform the export and when. Export job descriptions have some mandatory attributes like the account, product, layer and unit (deutsch: Blatt). Therefore, every new export job starts with an export job description.

// Every export job has an account, product, user defined job number and initiator
ExportJobDescription description = ExportJobDescription.getDefaultDescriptor();
description.setInitiator("2758");
description.setAccount("Bruse");
description.setProduct("WU3");
description.setJobnumber("Bruse_0815");

// The unit defines the region to export
Unit unit = Unit.getDefaultUnit();
unit.setValue("821");
description.addUnit(unit);

// Export data from the products GML layer
Layer layer = Layer.getDefaultLayer();
layer.setProduct("WU3");
layer.setName("GML");
description.addLayer(layer);

Export job descriptions have to be valid. For instance, there will be some mandatory fields. You can validate job descriptions. Actually, every NF4J operation processing your job description will validate and reject it, if it is incorrect or incomplete.

if (description.isValid()) {
    System.out.println("Your job description is valid. Proceed.");
}

The next step to send an export job would be to set up a connection to your nF server. Since NF4J supports nF's proprietary servlet-based HTTP interface, you can instantiate such a HTTP connection by passing the IP address of your nF server.

HTTPConnection connection = new HTTPConnection("193.178.156.20");

Now everything is prepared to create a new export job.

AsyncExportJob job = new AsyncExportJob(description, connection);

Export jobs are implemented in an asynchronous fashion. This means that its main operations are executed without blocking the calling thread. Sending the export job to the nF may take some time. Meanwhile, the main application should listen for export job status events or changes. For instance, you may want to get notified as soon as an export job finishes. When an export job has finished, you can trigger an asynchronous download of the resulting CityGML file from the nF server. The following example shows how to send an export job, listen for export job status changes and download the resulting CityGML file.

public class Client implements JobStatusListener {

    public AsyncExportJob job;

    public static void main(String[] args) {		
        Client client = new Client();
        client.processJob();
    }
	
    public void processJob() {
        // Describe the export job
        ExportJobDescription description = ExportJobDescription.getDefaultDescriptor();
        description.setInitiator("2758");
        description.setAccount("Bruse");
        description.setProduct("WU3");
        description.setJobnumber("Bruse_0815");
		
        // Set at least one unit. You could also define a region polygon.
        Unit unit = Unit.getDefaultUnit();
        unit.setValue("821");
        description.addUnit(unit);
		
        // Set at least one layer
        Layer layer = Layer.getDefaultLayer();
        layer.setProduct("WU3");
        layer.setName("GML");
        description.addLayer(layer);
		
        // Create a new export job with the job description and a HTTP connection
        job = new AsyncExportJob(description, new HTTPConnection("193.196.136.164"));
	
        // Register a job status listener
        job.addJobStatusListener(this);
		
        try {
            // Send the export job to the nF server in a separate thread
            job.send();
        } catch (FailedTransmissionException ex) {
            // There was a problem with your connection or the job has been sent twice
            ex.printStackTrace();
        } catch (InvalidJobDescriptorException ex) {
            // The export job description is invalid
            ex.printStackTrace();
        }
    }

    // This client is a job status listener and will get notified upon job status changes
    @Override
    public void jobStatusChanged(JobStatusEvent event) {
        JobStatus status = (JobStatus) event.getSource();
        System.out.println(status);
        if (status == JobStatus.FINISHED) {
            try {
                // Start an asynchronous download of the resulting CityGML file
                job.downloadResult();
            } catch (FailedTransmissionException ex) {
                // Only finished jobs can download files
                ex.printStackTrace();
            }
        } else if (status == JobStatus.DOWNLOAD) {
            try {
                // Obtain the CityGML file handle
                File file = job.getResult();
                System.out.println("CityGML at " + file.getAbsolutePath());
            } catch (FailedTransmissionException ex) {
                // Download may have failed
                ex.printStackTrace();
            }
        }
    }

}

The above program will print the following lines to standard out.

LOCAL
SENT
PENDING
RUNNING
FINISHED
DOWNLOAD
CityGML at C:\Users\Bruse\SimStadtWorkspace\RegionChooser\nfExportJob_Bruse_0815_5087289282499517987.zip

In addition to the above listener mechanism, you can update and read the status of a sent job at any time as follows.

try {
    job.updateStatus();
catch (FailedTransmissionException ex) {
    // This happens if your job has not been sent to the nF yet.
}
System.out.println(job.getStatus());

There are some convenience methods to test the job status.

if (job.hasFinished()) {
    System.out.println("Perfect, lets request the result.");
}

if (job.hasFailed()) {
    System.out.println("Something went wrong.");
}

You are able to cancel a job at any time. Note that its remote nF counterpart cannot be canceled by this function. The NF4J job will just stop sending, polling or downloading.

job.cancel();

You can resume polling and downloading of a canceled job. Remember, both actions poll() and downloadResult() are executed asynchronously in their own threads. Polling via poll() only makes sense if you register a job status listener at the job.

job.poll();

job.downloadResult();

The same is true, if you know that a remote nF job exists with a particular job id. In that case, you have to instantiate the export job with its id and not with a description.

ExportJob job = new ExportJob(4711, new NFConnector("193.40.179.30"));
job.poll();
job.downloadResult();

Concept

nF Jobs and their NF4J Counterparts

NF4J jobs are proxy objects for their nF counterparts and try to synchronize themselfs with their nF counterparts. Therefore, both job types know the same status' as the nF jobs. Because the NF4J jobs have three aditional status'.

Job State Transitions

Every nF job has a status. As a job progresses, it will change its status. The job will be initialized with status 10, which means it is enqueued and waits for execution. Then the job will start to run and gets status code 20. While running, the job may encounter some serious problems from which it cannot recover, leading to status 30. If the job finishes as expected, then it will progress to status 40.

Figure 1: Export job state transitions. Yellow states are known by the local proxy job object only. Red states are known by both nF jobs and proxy NF4J jobs.

novaFACTORY

Servlets

nF offers three servlet-based HTTP interfaces. The RemoteOrder servlet takes XML-encoded export job descriptions and enqueues them for further execution. If you want to know the status of a sent export job you should call the RemoteStatus servlet. The RemoteImport servlet handles import jobs and enqueues them for execution.

>> wget --post-file=export_job.xml –O response.xml http://193.196.136.164:80/novaFACTORY/RemoteOrder

Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<RemoteOrderReport version="1.2.0">
    <jobId>684</jobId>
    <jobNumber>WU_Job_1</jobNumber>
</RemoteOrderReport>

Download the export job result with a request to the RemoteOrderServlet:

http://193.196.136.164:80/novaFACTORY/RemoteOrder?request=downloadJob&mode=0&jobId=686

Query the status of an export job with the RemoteStatus servlet:

>> wget –O response.xml http://193.196.136.164:80/novaFACTORY/RemoteStatus?jobid=685

Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<RemoteStatusReport version="1.1.0">
    <jobId>685</jobId>
    <status>10</status>
</RemoteStatusReport>

ADE Support

In order to load and store ADE elements along with your CityGML you have to configure nF's ADE support in the rds.ini file. You can activate ADE support on product level with

rdsCityGMLTransformADE.LBTEST=ade2gen! gen2ade!

or for all products with

rdsCityGMLTransformADE.*=ade2gen! gen2ade!