Difference between revisions of "Motu Client Java"
(→Building a download request) |
(→Getting the estimated download size) |
||
| Line 155: | Line 155: | ||
=== Getting the estimated download size === | === Getting the estimated download size === | ||
| + | |||
| + | Motu has an operation to estimate the size of a download request: | ||
| + | |||
| + | <source lang="java5"> | ||
| + | // get the estimated output size | ||
| + | RequestSize size = client.getSize(request); | ||
| + | |||
| + | // here is the size (in bytes) | ||
| + | Long bytes = size.getSizeInBytes(); | ||
| + | </source> | ||
=== Using the legacy Motu API === | === Using the legacy Motu API === | ||
Revision as of 17:29, 29 November 2017
Contents
Overview
Usage
Configure your project
Maven coordinates:
<dependency> <groupId>org.gcube.dataanalysis</groupId> <artifactId>motu-client</artifactId> <version>[1.0.0, 2.0.0)</version> </dependency>
Create a client
As a first step, you need to create a MotuClient object providing enough information to connect to the corresponding server:
MotuClient client = new MotuClient("server endpoint"); client.setUsername("username"); client.setPassword("password");
Setting the preferred download size
You can optionally specify the size of chunks to be downloaded. If not provided, the client will use the maximum size allowed by the server (currently most servers allow between 1 and 2 GB).
client.setPreferredDownloadSize(20*SizeUtils.MB);
Retrieving the product catalogue
A full catalogue containing all services published by the Motu server can be obtained with the code below.
Note: this might take some time to process as it recursively goes into nested server resources. If you only need some specific information, query for the specifically, as described in the following sections.
// retrieve the catalogue (it might take some time) MotuCatalogue catalogue = client.getCatalogue(); // get available services Collection<ServiceMetadata> services = catalogue.getServices();
A service usually contain different products (datasets). Typically there are products for different time resolution and/or different variables.
// get the list of products for a service Collection<ProductMetadataInfo> products = service.getProducts();
Product metadata can be obtained with:
ProductMetadataInfo product = ...; // get timestamps for which there are data available List<Calendar> times = product.getAvailableTimeCodes(); // the oldest timestamp in the dataset Calendar start = product.getFirstAvailableTimeCode(); // the most recent timestamp in the dataset Calendar end = product.getLastAvailableTimeCode(); // get the time resolution of the dataset (in hours) Long hours = product.getTimeResolution(); // get a list of depths for which there are data available List<Double> depths = product.getAvailableDepths(); // get the lowest depth value (i.e. closer to the surface) Double depth = product.getFirstAvailableDepth(); // get the highest depth value (i.e. the deeper level) Double depth = product.getLastAvailableDepth(); // get the set of variables in the dataset Collection<Variable> variables = product.getVariables(); // get the dimensions of the dataset (e.g. lat, lon, depth) Collection<Axis> axes = product.getDataGeospatialCoverage();
Getting the list of services
Instead of retrieving the full catalogue (it might be slow), you might want to get the list of available services, without any nested product information:
// get a shallow list of available services Collection<ServiceMetadata> services = client.listServices();
Getting product metadata
Similarly, once you know the service and product name, you can retrieve product metadata directly:
// get product metadata by service and product name ProductMetadataInfo product = describeProduct("serviceName", "productName");
Downloading products
Products can be downloaded using two approaches:
- the legacy Motu API (asynchronous, with limited download size);
- the enhanced gCube API (synchronous, without any limitation on the download size).
Building a download request
Once you've identified the product you want to download, a download request has to be prepared with references to the product, bounding box, time frame and variables.
// build a download request DownloadRequest request = new DownloadRequest(); // the service name is mandatory request.setService("MEDSEA_ANALYSIS_FORECAST_PHYS_006_001-TDS"); // product name is also mandatory request.setProduct("cmemsv02-med-ingv-cur-an-fc-d"); // optionally, set the longitude range. If not set, the whole extent is downloaded request.setxRange(15d, 20d); // optionally, set the latitude range. If not set, the whole extent is downloaded request.setyRange(35d, 40d); // optionally, set the depth range. If not set, the whole depth extent is downloaded request.setzRange(1.4721018075942993, 5334.64794921875); // optionally, set the time window. If not set, all timestamps are downloaded request.settRange("2014-01-01 00:00:00", "2014-01-30 00:00:00"); // this seems to be mandatory. request.setScriptVersion("1.4.00-20170410143941999"); // process the request in asynchronous mode. request.setMode("status"); // the output format (no alternatives here) request.setOutput("netcdf"); // optionally set which variables to download. If not set, all of them are downloaded request.addVariable("vomecrty"); request.addVariable("vozocrtx");
Getting the estimated download size
Motu has an operation to estimate the size of a download request:
// get the estimated output size RequestSize size = client.getSize(request); // here is the size (in bytes) Long bytes = size.getSizeInBytes();
Using the legacy Motu API
Using the enhanced API
Under the hood
TODO
