Example: Using the SdmxStructureParser

This example will show a simple demonstration of the SdmxStructureParser component in which an SDMX Structure Definition file will be converted into the equivalent Java object representation and then transformed back into XML. The Structure Parser component contains the functionality to parse SDMX-ML and SDMX-EDI into SDMX Beans, and vice versa. It also contains the ability to resolve cross references and external references.

A zip file containing a complete Eclipse project, as well as a sample Structure Definition file can be obtained from here.

Pre-requisites
You will need an Eclipse project that has Maven capabilities (see configuring Eclipse) and an SDMX Structure Definition file. If you do not a Structure Definition file you can obtain a sample one from this example’s zip file. Please copy your Structure Definition file into your Eclipse project.

You will also be using Spring since this significantly simplifies the bean instantiation, so a Spring beans file will be required and placed into your Eclipse project. For further information about how to set up a Spring Beans file, please follow this link.

Adding dependencies
This example uses the Fusion Components:

• SdmxApi – which provides the interfaces.
• SdmxBeans – which provides the SDMX Beans.
• SdmxStructureParser – which provides the parsing facility to convert a file from the XML state to the object state and vice versa.

These 3 dependencies need to be added to the POM file in your project. If your Maven settings file has been set up correctly, and Eclipse is pointing to the correct m2 directory, then these dependencies will be downloaded as well as any dependencies that the Fusion Components require.

Example code
The following example demonstrates how to convert an SDMX Structure Definition file into SdmxBeans and then ask the Beans for information.

@Service
public class SdmxStructureParserExample {

	@Autowired
	private StructureParsingManager structureParsingManager;

	public static void main(String[] args) throws Exception {
		ApplicationContext context = new ClassPathXmlApplicationContext("spring-beans.xml");
		SdmxStructureParserExample demo = context.getBean(SdmxStructureParserExample.class);
		demo.parseDocument();
	}

	private void parseDocument() throws Exception {
		URI fileLocation = new URI("src/main/resources/sampleStructure.xml");
		StructureWorkspace workspace = structureParsingManager.parseStructures(fileLocation);
		SdmxBeans beans = workspace.getStructureBeans(false);
		System.out.println(beans.getCodelists().size());
		System.out.println(beans.getKeyFamilies().size());

		workspace.writeStructures(SDMX_SCHEMA.VERSION_TWO, System.out, false);
	}
}

Create a Java class called “SdmxStructureParserExample ” (if you wish to use another name, you will need to change the line with context.getBean in it to reflect your class name) in the package of your choice. Note that this package will need to be component scanned, so update your spring beans file accordingly.

When the Java application is run, the output will display how many codelists there are in your Structure Definition file, show how many KeyFamilites there are in your Structure Definition file and then output the Structure Definition file in SDMX format 2.0.

Once you have the example running, it is recommended that you experiment with the beans class and explorer the other functionality that the SdmxStructureParser provides.

Code Explanation
The class is marked as @Service to enable the field “structureParsingManager” to be autowired. This means that Spring will instantiate this field with an implementation from the Fusion Components.

Within the Java main method, the ApplicationContainer must be setup to point at your Spring Beans file, so you will need to ensure that the value in the ClassPathXmlApplicationContext is correct.

In the parseDocument method, we are asking for a URI for our Structure Definition file. Please ensure that this is correct for your file. We then ask the StructureParsingManager instance (which was instantiated via Spring) to parse this structure which returns a StructureWorkspace instance which provides a mechanism to retrieve the contained beans and convert the beans to different versions. The Workspace is asked to return the SdmxBeans contained within and once we have an instance of the SdmxBeans, this object can be interrogated for all manner of thins (such as Codelists, data flows, constraints, etc.). In this example we ask for the codelists and key families and output these to the screen.

The final line in the parseDocument method shows how to use the workspace to convert the structure definition into the SDMX version 2.0 form. The method “writeStructures”, takes 3 arguments: the output format (2.0 in the example), an OutputStream to write the output to (System.out in the example) and whether to resolve cross-references (set to false in the example). This line will process the Java representation of the Structure Definition and create an equivalent XML version conforming to the SDMX 2.0 form.

Troubleshooting
If the above example failed to run, please check the following:

• Ensure that the Fusion Components were downloaded from the repository. This can be seen in Eclipse’s “Package Explorer” view, there should be a section called “Maven Dependencies”. If there isn’t there is a problem with your Maven settings. If there is, expand this folder and check that the required dependencies have been downloaded.
• Ensure that the Spring bean file is within your project and that the code (in the main method) is referring to the correct location that the bean file is in.
• Ensure that the Spring bean file has been configured to scan the package containing your Java class.
• Ensure that the Sdmx Structure Definition file is within your project and that the code (in the parse document method) is referring to the correct location that the file is in.
• Ensure that your project is running with a Java of version 1.5 or later.