v2_1 2011-05 files

airosa · Jun 27, 2014 · 0d4b4b1 · 0d4b4b1
1 parent d5fef58
commit 0d4b4b1
Show file tree

Hide file tree

Showing 9 changed files with 4,539 additions and 0 deletions.
diff --git a/v2_1/rest/README.txt b/v2_1/rest/README.txt
@@ -0,0 +1,20 @@
+WADL for the SDMX RESTful API specification.
+------------------------------------------
+
+File listing
+- SDMXRestTypes.xsd: XSD for defining types of paramteres used in WADL. It is imported by the WADL file.
+- sdmx-rest.wadl: The WADL file of the REST specifications
+- RestTestClient.java sample client java code for the wadl2java tool.
+- wadl.xsd: The XSD of the WADL file. It can be used for validating WADL files.
+- xml.xsd: The XSD for the http://www.w3.org/XML/1998/namespace namespace. It is included so the schemas can be validated offline.
+
+Builiding a client from WADL
+Using the wadl2java it generates the appropriate client stubs in Java.
+Sample command:
+wadl2java -o src -p org.estat.rest -a sdmx-rest.wadl
+To call these client stubs see the sample code in RestTestClient.java.
+
+Resources
+http://www.w3.org/Submission/wadl/
+http://java.net/projects/wadl/
+http://java.net/downloads/wadl/latest/
diff --git a/v2_1/rest/src/RestTestClient.java b/v2_1/rest/src/RestTestClient.java
@@ -0,0 +1,129 @@
+/**
+ * Sample client for the SDMX RESTful API using stubs auto-generated from wadl2java 
+ * @author Spyros Liapis
+ * 
+ */
+package rest.client;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.net.MalformedURLException;
+import java.util.List;
+
+import javax.activation.DataSource;
+import javax.xml.bind.JAXBException;
+
+import org.estat.rest.ErrorException;
+import org.estat.rest.HttpWwwSdmxOrgSdmxrestservice.AgencyschemeAgencyIDResourceIDVersion;
+import org.estat.rest.HttpWwwSdmxOrgSdmxrestservice.CodelistAgencyIDResourceIDVersion;
+import org.estat.rest.HttpWwwSdmxOrgSdmxrestservice.DataFlowRefKeyProviderRef;
+import org.estat.rest.HttpWwwSdmxOrgSdmxrestservice.SchemaContextAgencyIDResourceIDVersion;
+import org.sdmx.resources.sdmxml.schemas.v2_1.common.CodedStatusMessageType;
+import org.sdmx.resources.sdmxml.schemas.v2_1.common.TextType;
+import org.sdmx.resources.sdmxml.schemas.v2_1.message.ErrorType;
+import org.sdmx.resources.sdmxml.schemas.v2_1.message.StructureType;
+
+public class RestTestClient {
+
+
+	/**
+	 * @param args
+	 */
+	public static void main(String[] args) {
+
+		try {
+
+			// get Data
+			DataFlowRefKeyProviderRef data = new DataFlowRefKeyProviderRef("ESTAT.B3,STS_IND_A,1.0", "A.FR+DE...WXIND", "FR1");
+			DataSource dsdData = data.getAsApplicationVndSdmxStructurespecificdataXmlVersion21("2008", null, "2010-08-14T00:03:12+00:03", 12, null, null, null);
+
+			/*
+			 * the getAsApplication*() methods return the raw response in a Datasource.
+			 * In this case no deserialisation occurs. The response is acquired by getting Datasource.getInputStream().
+			 * For determining the response content the Datasource.getContentType() should be used to determine if the desired
+			 * representation has been returned or an error occurred. 
+			 */
+			System.out.println("content type:" + dsdData.getContentType());
+			if ( dsdData.getContentType().equals("application/vnd.sdmx.structurespecificdata+xml;version=2.1")) {
+				// get StructureSpecificData SDMX-ML from the Datasource
+				InputStream compactIs = dsdData.getInputStream();
+				InputStreamReader ir = new InputStreamReader(compactIs);
+				BufferedReader br = new BufferedReader(ir);
+				String line = "";
+				System.out.println("response:");
+				while ((line = br.readLine()) != null) {
+					System.out.println(line);
+				}
+			} else if (dsdData.getContentType().equals("application/vnd.sdmx.error+xml;version=2.1")) {
+				// get the SDMX-ML Error message from the Datasource 
+				InputStream errorIs = dsdData.getInputStream();
+				// parse and handle error...
+			}
+
+
+			DataSource genericXmlVersion21 = data.getAsApplicationVndSdmxGenericdataXmlVersion21("2008", null, "2010-08-14T00:03:12+00:03", null, null, null, null);
+
+
+
+			// get Codelist
+			CodelistAgencyIDResourceIDVersion clist = new CodelistAgencyIDResourceIDVersion("ESTAT", "CL_FREQ", "1.0");
+			DataSource clXmlVersion21 = clist.getAsApplicationVndSdmxStructureXmlVersion21("allstubs", null);
+
+
+
+			/*
+			 * Besides the getApplication*() method for getting raw the response wrapped in a Dataset,
+			 * it's possible to call the specific getter so as to deserialise the response to beans created by the wadl2java to hold information in XML.
+			 * e.g. StrutureType for the Structure messages.
+			 * 
+			 * In this case the error messages are deserialised also. Therefore an ErrorException is thrown and the information
+			 * of the error message can extracted as shown below.
+			 */
+			try {
+				StructureType structure = clist.getAsStructureType("allstubs", null);
+			} catch (ErrorException e) {
+				ErrorType error = e.getFaultInfo();
+				List<CodedStatusMessageType> list = error.getErrorMessage();
+				CodedStatusMessageType statusTextType = list.get(0);
+				// error code
+				statusTextType.getCode();
+				// error texts in different lang
+				List<TextType> texts = statusTextType.getText();
+				for (TextType text : texts) {
+					text.getLang();
+					text.getValue();
+				}
+			}
+
+			// "" is equivalent to "latest". It's should be used null in the URL template parameters. This holds only for parameters.
+			CodelistAgencyIDResourceIDVersion clist2 = new CodelistAgencyIDResourceIDVersion("ESTAT", "CL_FREQ", "");
+			DataSource xlXmlVersion21_2 = clist2.getAsApplicationVndSdmxStructureXmlVersion21("allstubs", null);
+
+
+			// get all agencies available in from the WS
+			AgencyschemeAgencyIDResourceIDVersion  agSch = new AgencyschemeAgencyIDResourceIDVersion("all", "AGENCIES", "1.0");
+			DataSource agDatasource = agSch.getAsApplicationVndSdmxStructureXmlVersion21();
+
+
+			// get CompactSchema
+			SchemaContextAgencyIDResourceIDVersion schema = new SchemaContextAgencyIDResourceIDVersion("datastructure", "ESTAT", "STS", "2.1");
+			DataSource compactSchema = schema.getAsApplicationVndSdmxSchemaXmlVersion21("STS_INDICATOR", null);
+
+
+
+		} catch (JAXBException e) {
+			// TODO Auto-generated catch block
+			e.printStackTrace();
+		} catch (MalformedURLException e) {
+			// TODO Auto-generated catch block
+			e.printStackTrace();
+		} catch (IOException e) {
+			// TODO Auto-generated catch block
+			e.printStackTrace();
+		}
+
+	}
+
+}
diff --git a/v2_1/rest/src/SDMXRestTypes.xsd b/v2_1/rest/src/SDMXRestTypes.xsd
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    xmlns="http://www.sdmx.org/resources/rest/schemas/v2_1/types"
+    xmlns:common="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common"
+    targetNamespace="http://www.sdmx.org/resources/rest/schemas/v2_1/types"> 
+    <xs:import namespace="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" schemaLocation="../schemas/SDMXCommonReferences.xsd"/>
+
+    <xs:simpleType name="KeyType">
+        <xs:annotation>
+            <xs:documentation>The key of the artefact to be returned. Wildcarding is supported by omitting the dimension code for the dimension to be wildcarded. 
+                For example, if the following series key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, 
+                then the following series key can be used to retrieve the data for all currencies against the euro: D..EUR.SP00.A. 
+                The OR operator is supported using the + character. For example, the following series key can be used to retrieve the exchange rates 
+                against the euro for both the US dollar and the Japanese Yen: D.USD+JPY.EUR.SP00.A.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="([A-z0-9_@$\-]+)(\.(([A-z0-9_@$\-]+)(\+([A-z0-9_@$\-]+))*)?)*"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="ProviderRefType">
+        <xs:annotation>
+            <xs:documentation>A string identifying the provider. The syntax is agency id, provider id, separated by a “,”. For example: AGENCY_ID,PROVIDER_ID.
+                In case the string only contains one out of these 2 elements, it is considered to be the provider id, i.e. ALL,PROVIDER_ID.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="([A-z][A-z0-9_\-]*(\.[A-z][A-z0-9_\-]*)*\,)?([A-z0-9_@$\-]+)"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="FlowRefType">
+        <xs:annotation>
+            <xs:documentation>A string identifying the dataflow. The syntax is agency id, artefact id, version, separated by a “,”. For example: AGENCY_ID,FLOW_ID,VERSION
+                In case the string only contains one out of these 3 elements, it is considered to be the flow id, i.e. ALL,FLOW_ID,LATEST
+                In case the string only contains two out of these 3 elements, they are considered to be the agency id and the flow id, i.e. AGENCY_ID,FLOW_ID,LATEST
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="([A-z0-9_@$\-]+)|(([A-z][A-z0-9_\-]*(\.[A-z][A-z0-9_\-]*)*)(\,[A-z0-9_@$\-]+)(\,(latest|([0-9]+(\.[0-9]+)*)))?)"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+
+    <xs:simpleType name="allType">
+        <xs:restriction base="xs:string">
+            <xs:pattern value="all"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="latestType">
+        <xs:restriction base="xs:string">
+            <xs:pattern value="latest"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="IDType">
+        <xs:annotation>
+            <xs:documentation>IDType for WADL is used to indicate the possible values for a WADL Resource parameter.</xs:documentation>
+        </xs:annotation>
+        <xs:union memberTypes="allType common:IDType"></xs:union>
+    </xs:simpleType>
+
+    <xs:simpleType name="NCNameIDType">
+        <xs:annotation>
+            <xs:documentation>NCNameIDType for WADL is used to indicate the possible values for a WADL Resource parameter.</xs:documentation>
+        </xs:annotation>
+        <xs:union memberTypes="allType common:NCNameIDType"></xs:union>
+    </xs:simpleType>
+
+    <xs:simpleType name="VersionType">
+        <xs:annotation>
+            <xs:documentation>VersionType for WADL is used to indicate the possible values for a WADL Resource parameter</xs:documentation>
+        </xs:annotation>
+        <xs:union memberTypes="latestType allType common:VersionType"></xs:union>
+    </xs:simpleType>
+
+    <xs:simpleType name="DetailType">
+        <xs:annotation>
+            <xs:documentation>DetailType for WADL is used to indicate the possible values for a WADL Resource parameter. 
+                This parameter specifies the desired amount of information to be returned. 
+                For example, it is possible to instruct the web service to return only basic information about the maintainable artefact (i.e.: id, agency id, version and name). 
+                Most notably, items of item schemes will not be returned (for example, it will not return the codes in a code list query). 
+                Possible values are: "allstubs" (all artefacts should be returned as stubs ), "referencestubs" (referenced artefacts should be returned as stubs ) 
+                and full (all available information for all artefacts should be returned ).
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="allstubs"/>
+            <xs:pattern value="referencestubs"/>
+            <xs:pattern value="full"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="ReferencesType">
+        <xs:annotation>
+            <xs:documentation>ReferencesType for WADL is used to indicate the possible values for a WADL Resource parameter.
+                This parameter instructs the web service to return (or not) the artefacts referenced by the artefact to be returned 
+                (for example, the code lists and concepts used by the data structure definition matching the query), 
+                as well as the artefacts that use the matching artefact (for example, the dataflows that use the data structure definition matching the query). 
+                Possible values are: "none" (no references will be returned), "parents" (the artefacts that use the artefact matching the query), 
+                "parentsandsiblings" (the artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts), 
+                "children" (artefacts referenced by the artefact to be returned), "descendants" (references of references, up to any level, will also be returned), 
+                "all" (the combination of parentsandsiblings and descendants).  In addition, a concrete type of resource, as defined in 3.3.1, may also be used (for example, references=codelist).
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="none"/>
+            <xs:pattern value="parents"/>
+            <xs:pattern value="parentsandsiblings"/>
+            <xs:pattern value="children"/>
+            <xs:pattern value="descendants"/>
+            <xs:pattern value="all"/>
+            <!-- Specific reference artefact type -->
+            <xs:pattern value="datastructure"/>
+            <xs:pattern value="metadatastructure"/>
+            <xs:pattern value="categoryscheme"/>
+            <xs:pattern value="conceptscheme"/>
+            <xs:pattern value="codelist"/>
+            <xs:pattern value="hierarchicalcodelist"/>
+            <xs:pattern value="organisationscheme "/>
+            <xs:pattern value="agencyscheme"/>
+            <xs:pattern value="dataproviderscheme"/>
+            <xs:pattern value="dataconsumerscheme"/>
+            <xs:pattern value="organisationunitscheme"/>
+            <xs:pattern value="dataflow"/>
+            <xs:pattern value="metadataflow"/>
+            <xs:pattern value="reportingtaxonomy"/>
+            <xs:pattern value="provisionagreement"/>
+            <xs:pattern value="structureset"/>
+            <xs:pattern value="process"/>
+            <xs:pattern value="categorisation"/>
+            <xs:pattern value="contentconstraint"/>
+            <xs:pattern value="attachmentconstraint"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+	<xs:simpleType name="SchemaContextType">
+		<xs:annotation>
+            <xs:documentation>SchemaContextType for WADL is used to indicate the possible values for a WADL Resource parameter.
+                The value of this parameter determines the constraints that need to be taken into account, when generating the schema. 
+                If datastructure or metadatastructure is used, constraints attached to the DSD or MSD must be applied when generating the schema. 
+                If dataflow or metadataflow is used, constraints attached to the dataflow or metadataflow and to the DSD or MSD used in the dataflow or metadataflow must be applied when generating the schema. 
+                If provisionagreement is used, constraints attached to the provision agreement, as well as to the dataflow or metadafalow used in the agreement and the DSD or MSD 
+                used in the dataflow or metadataflow must be applied when generating the schema.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="datastructure"/>
+            <xs:pattern value="dataflow"/>
+            <xs:pattern value="provisionagreement"/>
+            <xs:pattern value="metadatastructure"/>
+            <xs:pattern value="metadatafow"/>                        
+        </xs:restriction>
+	</xs:simpleType>
+
+	<xs:simpleType name="DataDetailType">
+        <xs:annotation>
+            <xs:documentation>DataDetailType for WADL is used to indicate the possible values for a WADL Resource parameter.
+                This attribute specifies the desired amount of information to be returned. 
+                For example, it is possible to instruct the web service to return data only (i.e. no attributes). 
+                Possible options are: "full" (all data and documentation, including annotations - This is the default), 
+                "dataonly" (attributes, and therefore groups, will be excluded from the returned message), 
+                "serieskeysonly" (returns only the series elements and the dimensions that make up the series keys. 
+                This is useful for performance reasons, to return the series that match a certain query, without returning the actual data), 
+                "nodata" (returns the groups and series, including attributes and annotations, without observations).
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="full"/>
+            <xs:pattern value="dataonly"/>
+            <xs:pattern value="serieskeysOnly"/>
+            <xs:pattern value="nodata"/>
+        </xs:restriction>
+    </xs:simpleType>
+</xs:schema>