How to program a {@link Int.ecb.gesmescb.event.GESMESCBReader}


The operations to implement

Please have a look at the interface {@link Int.ecb.gesmescb.event.GESMESCBReader}. It specifies all functions that must be implemented. In fact, this interface extends the {@link Int.ecb.gesmescb.event.GESMESCBEventSource}, which defines operations for Listener connection and disconnection. However, this implies minimum additional coding if you extend the {@link Int.ecb.gesmescb.event.GESMESCBEventSourceAdapter} or if this is not possible by delegate to a {@link Int.ecb.gesmescb.event.GESMESCBEventSourceHelper}.

So there are mainly three things to implement. Each of these will be called once by the application:

Just one more remark. You may want to also implement the interface {@link Int.ecb.gesmescb.util.Named}. Names could be used by more intelligent applications to address components. This, however, does not imply much programming overhead. You find one way of how to do it in YourReader.java.

{@link Int.ecb.gesmescb.GESMESCBObject}s

The operation {@link Int.ecb.gesmescb.event.GESMESCBReader#run()} generates all {@link Int.ecb.gesmescb.GESMESCBObject}s which represent the input. In a loader-setup, these eventually reach the {@link Int.ecb.gesmescb.event.GESMESCBEventListenerAdapter#handle()} operation and are written to the {@link Int.ecb.gesmescb.event.GESMESCBWriter}'s output destination. In a checker-setup, they are normally not written, of course, but only checked. There are three categories of GESMESCBObjects:

The method run that you write will generate and dispatch a sequence of the above-mentioned objects in a timely order. Such a sequence always starts with an InterchangeBegin and ends with an InterchangeEnd. Between these objects there can be one or more messages.

Interchange with one message

Each message starts with a MessageBegin and ends with a MessageEnd. Enclosed between these there come either structural definition objects or data objects, depending on the type of message it is. A structural definition message encloses first a sequence of CodeLists, then StatisticalConcepts, and finally KeyFamily objects.

Message containing structural definitions

A data message encloses first a sequence of TimeSeries and then a sequence of Attributes.

Message containing data

Since recently, it is permitted to mix TimeSeries and Attributes arbitrarily. This is less suited to EDIFACT syntax, but better for OECD-style CSV and probably XML. The {@link Int.ecb.gesmescb.edifact.EDIFACTWriter} can now postpone writing of Attributes. Other {@link Int.ecb.gesmescb.event.GESMESCBWriter}s must also support mixed data sequences.

Message containing data in mixed mode

Logging

The package {@link Int.ecb.logging} tries to mimic a small subset of java.util.logging, which is not implemented on platforms earlier than Java 1.4. When Java 1.4 will be sufficiently widespread, the package could become obsolete.

Logging is typically configured via a configuration file. Its location is determined by the system property Int.ecb.logging.config.file.

The logging configuration uses a tree-shaped model. I.e. setting the log level of a parent node {@link Int.ecb.logging.Logger} also sets the child node Loggers.

The log {@link Int.ecb.logging.Level}s to be used when generating log messages are {@link Int.ecb.logging.Level#SEVERE}, {@link Int.ecb.logging.Level#WARNING}, {@link Int.ecb.logging.Level#INFO}, {@link Int.ecb.logging.Level#CONFIG}, {@link Int.ecb.logging.Level#FINE}, {@link Int.ecb.logging.Level#FINER}, {@link Int.ecb.logging.Level#FINEST}. The additional Levels {@link Int.ecb.logging.Level#OFF}, {@link Int.ecb.logging.Level#ALL} can be used to set the sensitivity of Loggers.

There is a well-defined correspondence between the Levels and the {@link Int.ecb.gesmescb.error.ErrorWatcher} severity codes (which are so far mirrored by the {@link Int.ecb.gesmescb.event.ErrorEvent} severity codes): {@link Int.ecb.gesmescb.error.ErrorWatcher#FAILURE} and {@link Int.ecb.gesmescb.error.ErrorWatcher#ERROR} are SEVERE, {@link Int.ecb.gesmescb.error.ErrorWatcher#WARNING} corresponds to a WARNING, and {@link Int.ecb.gesmescb.error.ErrorWatcher#OK} (which is {@link Int.ecb.gesmescb.event.ErrorEvent#INFO}) corresponds to a INFO. Obviously, the semantic difference (internal/external problem) between FAILURE and ERROR are not reflected in the logging API.

The finer log levels should be used according to the following proposed policy:

CONFIG
A configuration decision is loaded e.g. from the preferences.
FINE
An {@link Int.ecb.gesmescb.InterchangeBegin}, {@link Int.ecb.gesmescb.InterchangeEnd}, {@link Int.ecb.gesmescb.MessageBegin}, or {@link Int.ecb.gesmescb.MessageEnd} is constructed or finally written.
FINER
A {@link Int.ecb.gesmescb.CodeList}, {@link Int.ecb.gesmescb.StatisticalConcept}, {@link Int.ecb.gesmescb.KeyFamily}, {@link Int.ecb.gesmescb.TimeSeries}, or {@link Int.ecb.gesmescb.Attribute} is constructed or finally written.
FINEST
A {@link Int.ecb.gesmescb.Contact}, {@link Int.ecb.gesmescb.KeyFamilyComponent}, {@link Int.ecb.gesmescb.Observation} is constructed or finally written. Also all finer operations would be logged with this Level, particularly forwarding of {@link Int.ecb.gesmescb.GESMESCBObject}s.

Of course, these rules are not binding. Particularly other activities, like opening and closing files and databases could be logged with FINE or even INFO if central to the activity.

Configuration

The package {@link Int.ecb.prefs} tries to mimic a small subset of java.util.prefs, which is not implemented on platforms earlier than Java 1.4. When Java 1.4 will be sufficiently widespread, the package could become obsolete.

Preferences are typically read from a configuration file. Its location is determined by the system property Int.ecb.prefs.config.file. The file is in the simple textual {@link java.util.Properties} format.

Java allows to set properties also via the -D parameter on the command line.

Many classes retrieve essential parameters from the configuration setup. Most importantly, reading sources and writing destinations can be set this way.