Quick Start Example

Structure

Minimal Structure Read Example

public class QuickStart {

     /**
     * Read JSON structure file, write as SDMX-ML v3.0
     */
    public static void main(String[] args) {
        SdmxJsonModule.register();

        SdmxBeans beans = getStructures("src/main/resources/Structures.json");
        Path outFile = Paths.get("src/main/resources/Structures.xml");
        OutputStream out = PathUtil.getOutputStream(outFile, false);

        StaxStructureWriterEngineV3.getInstance().writeStructures(beans, Collections.emptyMap(), out);
    }


    /**
     * Reads SdmxBeans from a file or URL
     */
    private static SdmxBeans getStructures(String uri) {
        StructureReaderManager srm = new StructureReaderManagerImpl();
        try (ReadableDataLocation rdl = new ReadableDataLocationTmp(uri) ){
            return srm.parseStructures(rdl);
        }
    }
}

Maven dependencies

<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-json</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-ml</artifactId>
    <version>4.2.0</version>
</dependency>

Data

Minimal Data Writer Example

Manually create a Data Structure Definition and DataWriterEngine, write the XML dataset to System.out

public class QuickStart {

    /**
     * Create a DataStructureBean and write data
     */
    public static void main(String[] args) {
        DataStructureBean dsd = TestDSDUtil.generateDSD(true, true, "FREQ", "COUNTRY", "INDICATOR");

        SDMX_SCHEMA sdmxMLVersion = SDMX_SCHEMA.VERSION_THREE;
        boolean prettyPrint = true;
        DataWriterEngine dwe = new CompactDataWriterEngine(sdmxMLVersion, System.out, prettyPrint);

        //Start the dataset for the dataflow
        dwe.startDataset(null, null, dsd, null);

        dwe.startSeries();
        dwe.writeSeriesKeyValue("FREQ", "A");
        dwe.writeSeriesKeyValue("COUNTRY", "US");
        dwe.writeSeriesKeyValue("INDICATOR", "BIRTHS");
        dwe.writeTimeSeries("2024", "12");
        dwe.writeTimeSeries("2025", "13");

        dwe.startSeries();
        dwe.writeSeriesKeyValue("FREQ", "A");
        dwe.writeSeriesKeyValue("COUNTRY", "FR");
        dwe.writeSeriesKeyValue("INDICATOR", "BIRTHS");
        dwe.writeTimeSeries("2024", "11");
        dwe.writeTimeSeries("2025", "12");

        dwe.close();
    }
}

Maven dependencies

<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-im</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-ml</artifactId>
    <version>4.2.0</version>
</dependency>

Dynamic Data Writer Example

Pulls a Dataflow from the Global Registry, creates a DataWriterEngine in CSV format

public class QuickStart {

    /**
     * Reads a Dataflow from the Global Registry
     * and writes a dataset in a selected output format
     */
    public static void main(String[] args) {
        //Required for reading structures
        SdmxMLModule.register();

        //Required for writing dataset in CSV
        SdmxCsvModule.register();

        String url = getQueryURL();
        SdmxBeans beans = getStructures(url);

        DataFormat outFormat = SdmxCsvDataFormat.BASIC_V2;

        //Write the dataset
        writeDataset(beans, outFormat);
    }

    /**
     * Builds a URL to get the Dataflow and related DSD, Codelists
     * and Concepts
     */
    private static String getQueryURL() {
        //Get a specific dataflow from the SDMX Global Registry
        String entry = "https://registry.sdmx.org/sdmx/v2/structure/";

        //Template URL
        String query = "dataflow/ESTAT/HICP_AP_A/2.7.0?references=descendants";

        return entry + query;
    }

    /**
     * Reads SdmxBeans from a file or URL
     * @param url
     * @return
     */
    private static SdmxBeans getStructures(String url) {
        StructureReaderManager srm = new StructureReaderManagerImpl();
        try (ReadableDataLocation rdl = new ReadableDataLocationTmp(url) ){
            return srm.parseStructures(rdl);
        }
    }

    /**
     *
     * @param beans
     * @param outputFormat
     */
    private static void writeDataset(SdmxBeans beans, DataFormat outputFormat) {
        DataWriterEngine dwe = getDataWriter(outputFormat);

        //there is only 1
        DataflowBean df = (DataflowBean) beans.getDataflows().toArray()[0];

        //there is only 1
        DataStructureBean dsd = (DataStructureBean) beans.getDataStructures().toArray()[0];

        //Start the dataset for the dataflow
        dwe.startDataset(null, df, dsd, null);

        dwe.startSeries();
        dwe.writeSeriesKeyValue("FREQ", "A");

        //Output the Code ID for REF_AREA
        dwe.writeSeriesKeyValue("REF_AREA", "US");
        dwe.writeSeriesKeyValue("IND_TYPE", "AP");
        dwe.writeSeriesKeyValue("IDX_TYPE", "HICP");
        dwe.writeSeriesKeyValue("ITEM", "CP01111");
        dwe.writeAttributeValue("TITLE", "United States");

        //Output some dummy observation values for a couple of years
        dwe.writeTimeSeries("2024", "1222.1");
        dwe.writeTimeSeries("2025", "13.2");

        dwe.close();
    }


    private static DataWriterEngine getDataWriter(DataFormat outputFormat) {
        //The default format is used if null is passed to the DataWriterManager
        DataFormat defaultFormat = SdmxCsvDataFormat.BASIC_V2;
        DataWriterManager dwm = new DataWriterManagerImpl(defaultFormat);

        //The Data Writer engine in the format we asked for
        ISeriesObsDataWriterEngine dwe = dwm.getDataWriterEngine(outputFormat, System.out);

        //The DataWriterEngine has a simpler API for this use case
        return new RollupDataWriterEngine(dwe);
    }
}

Maven dependencies

<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-ml</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-csv</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-core-data</artifactId>
    <version>4.2.0</version>
</dependency>

Example Data Writer Formats

Builds on the previous example by introducing additional output formats, and by writing a series for every country in the REF_AREA Dimension. Configures the system so it is able to resolve labels for CSV and JSON formats.

public class QuickStart {

    /**
     * Reads a Dataflow from the Global Registry
     * and writes a dataset in a selected output format
     */
    public static void main(String[] args) {
        //Register modules for reading/writing different formats
        FusionSystem.register();
        SdmxJsonModule.register();
        SdmxMLModule.register();
        SdmxCsvModule.register();

        //Get a specific dataflow from the SDMX Global Registry
        String entry = "https://registry.sdmx.org/sdmx/v2/structure/";
        String query = "dataflow/ESTAT/HICP_AP_A/2.7.0?references=descendants";
        SdmxBeans beans = getStructures(entry+query);

        //Required by formats that resolve labels
        registerEnvironment(beans);


        //Change this number to change the format
        DataFormat outFormat = pickDataFormat(5);

        //Write the dataset
        writeDataset(beans, outFormat);
    }

    /**
     * This is only required for certain formats which output both
     * the ID and label for a Code, for example SDMX-JSON and SDMX-CSV
     * (if configured to output labels).
     *
     * The system needs to know where to get the structural metadata from,
     * this registers a global IStructureEnvironment which contains the means to
     * obtain the structures on request
     * @param beans
     */
    private static void registerEnvironment(SdmxBeans beans) {
        IStructureEnvironment environment = new StructureEnvironment(beans, null, null);
        SdmxBeanRetreivalContainer brc  = new SdmxBeanRetreivalContainer(environment);
        SingletonStore.registerInstance(brc);
    }

    /**
     * Some example formats
     */
    private static DataFormat pickDataFormat(int formatIdx) {
        switch(formatIdx) {
        case 1 : return SDMXMLDataFormat.COMPACT_2_0;
        case 2 : return SDMXMLDataFormat.COMPACT_2_1;
        case 3 : return SDMXMLDataFormat.COMPACT_3_0;
        case 4 : return SdmxCsvDataFormat.BASIC_V2;
        case 5 :
            //Output CSV with labels, use French formatting
            DATA_TYPE dt = DATA_TYPE.SDMX_CSV_2_0_0;
            String labels = "name";
            boolean normalizedTime = true;
            boolean includeBom = true;
            Locale locale = Locale.FRANCE;
            boolean includeSeriesKey = true;
            boolean includeObsKey = true;
            String rowHeaderValue = "x";
            boolean includeAction = false;
            DELIMITER delimiter = DELIMITER.TAB;
            SdmxCsvDataFormat csvFormat = new SdmxCsvDataFormat(dt,
                                                    labels,
                                                    normalizedTime,
                                                    includeBom,
                                                    locale,
                                                    includeSeriesKey,
                                                    includeObsKey,
                                                    rowHeaderValue,
                                                    includeAction,
                                                    delimiter);
            return csvFormat;
        case 6 :
        default:
            return new SdmxJsonDataFormat(DATA_TYPE.SDMXJSON_2_0_0, null);
        }
    }

    /**
     * Reads SdmxBeans from a file or URL
     * @param url
     * @return
     */
    private static SdmxBeans getStructures(String url) {
        StructureReaderManager srm = new StructureReaderManagerImpl();
        ReadableDataLocation rdl = new ReadableDataLocationTmp(url);
        try {
            return srm.parseStructures(rdl);
        } finally {
            rdl.close();
        }
    }

    /**
     *
     * @param beans
     * @param outputFormat
     */
    private static void writeDataset(SdmxBeans beans, DataFormat outputFormat) {
        DataWriterEngine dwe = getDataWriter(outputFormat);

        //The URN of the structure we want to create a dataset for
        IURNSingle<DataflowBean> dfUrn = URN.builder().
                agencyId("ESTAT").
                maintId("HICP_AP_A").
                version("2.7.0").
                buildSingle(DataflowBean.class);


        IDatasetStructures dsStructures = new DatasetStructures(dfUrn, beans);

        //ProvisionAgreementBean will be null
        ProvisionAgreementBean pa = dsStructures.getProvisionAgreement();

        //ESTAT:HICP_AP_A(2.7.0)
        DataflowBean df = dsStructures.getDataflow();

        //ESTAT:HICPAP(3.2.0)
        DataStructureBean dsd = dsStructures.getDataStructure();

        //Build SuperBean, which resolves all references (Codelists/Concepts)
        DataStructureSuperBean dsSb = DataStructureSuperBeanBuilder.getInstance().build(dsd, beans, null, null);

        //Start the dataset for the dataflow
        dwe.startDataset(pa, df, dsd, null);

        //Loop every Code in the codelist used by the REF_AREA Dimension
        EnumeratedListBean<?> countryCodelist = dsSb.getDimensionById("REF_AREA").getCodelist(true);
        for(EnumeratedItemBean countryCode : countryCodelist.getItems()) {
            dwe.startSeries();
            dwe.writeSeriesKeyValue("FREQ", "A");

            //Output the Code ID for REF_AREA
            dwe.writeSeriesKeyValue("REF_AREA", countryCode.getId());
            dwe.writeSeriesKeyValue("IND_TYPE", "AP");
            dwe.writeSeriesKeyValue("IDX_TYPE", "HICP");
            dwe.writeSeriesKeyValue("ITEM", "CP01111");

            //Ouptut the Code Name as the Title
            dwe.writeAttributeValue("TITLE", countryCode.getName());

            //Output some dummy observation values for a couple of years
            dwe.writeTimeSeries("2024", "1222.1");
            dwe.writeTimeSeries("2025", "13.2");
        }

        dwe.close();
    }


    private static DataWriterEngine getDataWriter(DataFormat outputFormat) {
        //The default format is used if null is passed to the DataWriterManager
        DataFormat defaultFormat = SdmxCsvDataFormat.BASIC_V2;
        DataWriterManager dwm = new DataWriterManagerImpl(defaultFormat);

        //The Data Writer engine in the format we asked for
        ISeriesObsDataWriterEngine dwe = dwm.getDataWriterEngine(outputFormat, System.out);

        //The DataWriterEngine has a simpler API for this use case
        return new RollupDataWriterEngine(dwe);
    }
}

Maven dependencies

<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-json</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-ml</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-csv</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-sdmx-im</artifactId>
    <version>4.2.0</version>
</dependency>
<dependency>
    <groupId>io.sdmx</groupId>
    <artifactId>fusion-core-data</artifactId>
    <version>4.2.0</version>
</dependency>