Commit 2b3dd2a6 authored by Daniel Eggert's avatar Daniel Eggert
Browse files

extended javadoc

parent fab5c602
...@@ -47,18 +47,7 @@ public class CloudCoverUpdateFromMetadataUrl { ...@@ -47,18 +47,7 @@ public class CloudCoverUpdateFromMetadataUrl {
private static final Random rand = new Random(); private static final Random rand = new Random();
public static void main(String[] args) throws Exception { public static void main(String[] args) throws Exception {
// landsat_tm(108), landsat_mss(107), landsat_8(104), landsat_7(112) short datasetids[] = new short[] { 250 }; // , 108, 107, 112 };
short datasetids[] = new short[] { 251 }; // , 108, 107, 112 };
// Timestamp start = Timestamp.MIN;
// Timestamp end = Timestamp.now();
// Timestamp end = start.plus(20, Timestamp.TimeUnits.DAYS);
// int seasonCode = 0;
// byte minCloudcover = 0;
// byte maxCloudcover = 100;
// double[] polygon = new double[] { -14, 32, 50, 32, 50, 64, -14, 64, -14, 32 };
// double[] polygon = new double[] { -180, -90, 180, -90, 180, 90, -180, 90, -180, -90 };
// final ByteBuffer buffer = ByteBuffer.allocate(200 * 1000 * 1000);
final SceneDatabase db = SceneDatabase.getInstance(); final SceneDatabase db = SceneDatabase.getInstance();
ExecutorService pool = Executors.newFixedThreadPool(20); ExecutorService pool = Executors.newFixedThreadPool(20);
......
...@@ -8,11 +8,16 @@ import de.potsdam.gfz.usgsapi.json.datamodels.TemporalFilter; ...@@ -8,11 +8,16 @@ import de.potsdam.gfz.usgsapi.json.datamodels.TemporalFilter;
import de.potsdam.gfz.usgsapi.json.response.JSONResponse; import de.potsdam.gfz.usgsapi.json.response.JSONResponse;
import net.minidev.json.JSONObject; import net.minidev.json.JSONObject;
/**
* Abstract base calss for search requests supporting temporal and spatial filters
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
*
* @param <T>
*/
public abstract class AbstractSearchRequest<T extends JSONResponse> extends JSONRequest<T> { public abstract class AbstractSearchRequest<T extends JSONResponse> extends JSONRequest<T> {
private static final String DATASET_NAME_KEY = "datasetName"; private static final String DATASET_NAME_KEY = "datasetName";
private static final String LOWERLEFT_KEY = "lowerLeft";
private static final String UPPERRIGHT_KEY = "upperRight";
private static final String TEMPORAL_FILTER_KEY = "temporalFilter"; private static final String TEMPORAL_FILTER_KEY = "temporalFilter";
private static final String SPATIAL_FILTER_KEY = "spatialFilter"; private static final String SPATIAL_FILTER_KEY = "spatialFilter";
private static final String INCLUDE_UNKNOWN_CLOUDCOVER_KEY = "includeUnknownCloudCover"; private static final String INCLUDE_UNKNOWN_CLOUDCOVER_KEY = "includeUnknownCloudCover";
......
...@@ -12,10 +12,9 @@ import net.minidev.json.parser.ParseException; ...@@ -12,10 +12,9 @@ import net.minidev.json.parser.ParseException;
/** /**
* Represents a dataset search request.<br> * Represents a dataset search request.<br>
* <br> * <br>
* This method is used to find datasets available for searching. By passing no parameters except node, all available datasets are returned. * This method is used to find datasets available for searching. By passing only API Key, all available datasets are returned. Additional parameters such as temporal range and
* Additional parameters such as temporal range and spatial bounding box can be used to find datasets that provide more specific data. * spatial bounding box can be used to find datasets that provide more specific data. The dataset name parameter can be used to limit the results based on matching the supplied
* The dataset name parameter can be used to limit the results based on matching the supplied value against the public dataset name with * value against the public dataset name with assumed wildcards at the beginning and end.
* assumed wildcards at the beginning and end.
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
* *
...@@ -26,13 +25,14 @@ public class DatasetSearchRequest extends AbstractSearchRequest<DatasetSearchRes ...@@ -26,13 +25,14 @@ public class DatasetSearchRequest extends AbstractSearchRequest<DatasetSearchRes
private Boolean publicOnly = null; private Boolean publicOnly = null;
/** /**
* @param code * Ctor
*
* @param apiKey * @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName * @param datasetName
* @param startDate * @param temporalFilter
* @param endDate * @param spatialFilter
* @param lowerLeft * @param publicOnly
* @param upperRight
*/ */
public DatasetSearchRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, Boolean publicOnly) { public DatasetSearchRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, Boolean publicOnly) {
super(RequestCode.DATASETS, apiKey); super(RequestCode.DATASETS, apiKey);
......
...@@ -30,6 +30,18 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse> ...@@ -30,6 +30,18 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse>
private final String[] entityIds; private final String[] entityIds;
private final Boolean machineOnly; private final Boolean machineOnly;
/**
* Ctor
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param entityIds
* - array of entityids the download options will be obtained for
* @param machineOnly
* - returns only options which are machine friendly
*/
public DownloadOptionsRequest(String apiKey, String datasetName, String[] entityIds, boolean machineOnly) { public DownloadOptionsRequest(String apiKey, String datasetName, String[] entityIds, boolean machineOnly) {
super(RequestCode.DOWNLOADOPTIONS); super(RequestCode.DOWNLOADOPTIONS);
this.apiKey = apiKey; this.apiKey = apiKey;
...@@ -38,6 +50,16 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse> ...@@ -38,6 +50,16 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse>
this.machineOnly = machineOnly; this.machineOnly = machineOnly;
} }
/**
* Ctor - same as {@link DownloadOptionsRequest#DownloadOptionsRequest(String, String, String[], boolean)} with machineOnly=<code>true</code>
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param entityIds
* - array of entityids the download options will be obtained for
*/
public DownloadOptionsRequest(String apiKey, String datasetName, String[] entityIds) { public DownloadOptionsRequest(String apiKey, String datasetName, String[] entityIds) {
this(apiKey, datasetName, entityIds, DEFAULT_MACHINE_ONLY_VALUE); this(apiKey, datasetName, entityIds, DEFAULT_MACHINE_ONLY_VALUE);
} }
......
...@@ -3,6 +3,7 @@ ...@@ -3,6 +3,7 @@
*/ */
package de.potsdam.gfz.usgsapi.json.request; package de.potsdam.gfz.usgsapi.json.request;
import de.potsdam.gfz.usgsapi.json.response.DownloadOptionsResponse;
import de.potsdam.gfz.usgsapi.json.response.DownloadResponse; import de.potsdam.gfz.usgsapi.json.response.DownloadResponse;
import net.minidev.json.JSONArray; import net.minidev.json.JSONArray;
import net.minidev.json.JSONObject; import net.minidev.json.JSONObject;
...@@ -12,10 +13,9 @@ import net.minidev.json.parser.ParseException; ...@@ -12,10 +13,9 @@ import net.minidev.json.parser.ParseException;
* Represents a download request.<br> * Represents a download request.<br>
* <br> * <br>
* The download request is used to generate a list of direct download URL's for data. To get available products, submit a downloadOptions request. All unavailable or invalid * The download request is used to generate a list of direct download URL's for data. To get available products, submit a downloadOptions request. All unavailable or invalid
* products are automatically excluded from the response.<br> * products are automatically excluded from the response.
* <br> *
* This request implements a rate limit on unattempted downloads. Download authorization records are created as a result of this request with the intent that the user will download * This request implements a rate limit based on a limit of 10 downloads that have not been completed within the last 15 minutes.
* the data before submitting subsequent requests. The rate limit is defined by 10 unattampted downloads within the last 10 minutes.
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
* *
...@@ -39,6 +39,21 @@ public class DownloadRequest extends JSONRequest<DownloadResponse> { ...@@ -39,6 +39,21 @@ public class DownloadRequest extends JSONRequest<DownloadResponse> {
private final String dataUse; private final String dataUse;
private final boolean stage; private final boolean stage;
/**
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param entityIds
* - array of entityids the download urls will be obtained for
* @param products
* - array of product names for each entityid (see {@link DownloadOptionsResponse})
* @param dataUse
* - Used to identify higher level products that this data may be used to create
* @param stage
* - If <code>true</code>, initiates a data stage command
*/
public DownloadRequest(String apiKey, String datasetName, String[] entityIds, String[] products, String dataUse, boolean stage) { public DownloadRequest(String apiKey, String datasetName, String[] entityIds, String[] products, String dataUse, boolean stage) {
super(RequestCode.DOWNLOAD); super(RequestCode.DOWNLOAD);
this.apiKey = apiKey; this.apiKey = apiKey;
...@@ -50,11 +65,15 @@ public class DownloadRequest extends JSONRequest<DownloadResponse> { ...@@ -50,11 +65,15 @@ public class DownloadRequest extends JSONRequest<DownloadResponse> {
} }
/** /**
* Convenience ctor, using the default value for products (STANDARD). * Convenience ctor, using the default value for products (STANDARD), dataUse (END_USER) and stage (FALSE)
* *
* @param apiKey * @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName * @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param entityIds * @param entityIds
* - array of entityids the download urls will be obtained for
*
*/ */
public DownloadRequest(String apiKey, String datasetName, String[] entityIds) { public DownloadRequest(String apiKey, String datasetName, String[] entityIds) {
this(apiKey, datasetName, entityIds, new String[] { DEFAULT_PRODUCTS_VALUE }, DEFAULT_DATAUSE_VALUE, DEFAULT_STAGE_VALUE); this(apiKey, datasetName, entityIds, new String[] { DEFAULT_PRODUCTS_VALUE }, DEFAULT_DATAUSE_VALUE, DEFAULT_STAGE_VALUE);
......
...@@ -10,10 +10,7 @@ import de.potsdam.gfz.usgsapi.json.response.HitsResponse; ...@@ -10,10 +10,7 @@ import de.potsdam.gfz.usgsapi.json.response.HitsResponse;
import net.minidev.json.parser.ParseException; import net.minidev.json.parser.ParseException;
/** /**
* Represents a hits request, returning the number of expected hits.<br> * This method is used in determining the number of hits a search returns. Because a hits request requires a search, this request takes the same parameters as the search request,
* <br>
* This method is used in determining the number of hits a search returns.
* Because a hits request requires a search, this request takes the same parameters as the search request,
* with exception to the non-search-field parameters; maxResults, startingNumber, and sortOrder. * with exception to the non-search-field parameters; maxResults, startingNumber, and sortOrder.
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
...@@ -24,11 +21,17 @@ public class HitsRequest extends AbstractFilteredSearchRequest<HitsResponse> { ...@@ -24,11 +21,17 @@ public class HitsRequest extends AbstractFilteredSearchRequest<HitsResponse> {
/** /**
* *
* @param apiKey * @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName * @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param temporalFilter * @param temporalFilter
* - temporal filter range
* @param spatialFilter * @param spatialFilter
* - spatial filter range
* @param filter * @param filter
* - additional filters
* @param includeUnknownCloudCover * @param includeUnknownCloudCover
* - flag for also include scenes with unknown cloud cover
*/ */
public HitsRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, SearchFilter filter, Integer minCloudCover, public HitsRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, SearchFilter filter, Integer minCloudCover,
Integer maxCloudCover, Boolean includeUnknownCloudCover) { Integer maxCloudCover, Boolean includeUnknownCloudCover) {
......
...@@ -8,18 +8,17 @@ import net.minidev.json.JSONObject; ...@@ -8,18 +8,17 @@ import net.minidev.json.JSONObject;
import net.minidev.json.parser.ParseException; import net.minidev.json.parser.ParseException;
/** /**
* Abstract base class for all requests
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
* *
*/ */
public abstract class JSONRequest<T extends JSONResponse> { public abstract class JSONRequest<T extends JSONResponse> {
private static final String NODE_KEY = "node"; private static final String APIKEY_KEY = "apiKey";
private static final String EARTHEXPLORER_NODE_VALUE = "EE";
private static final String APIKEY_KEY = "apiKey";
private static final String LATITUDE_KEY = "latitude"; private static final String LATITUDE_KEY = "latitude";
private static final String LONGITUDE_KEY = "longitude"; private static final String LONGITUDE_KEY = "longitude";
public static enum RequestCode { public static enum RequestCode {
LOGIN(true), LOGOUT(true), DATASETS(false), SEARCH(false), HITS(false), DOWNLOAD(false), DOWNLOADOPTIONS(false); LOGIN(true), LOGOUT(true), DATASETS(false), SEARCH(false), HITS(false), DOWNLOAD(false), DOWNLOADOPTIONS(false);
...@@ -50,15 +49,6 @@ public abstract class JSONRequest<T extends JSONResponse> { ...@@ -50,15 +49,6 @@ public abstract class JSONRequest<T extends JSONResponse> {
return this.code; return this.code;
} }
/**
* Adds the earthexplorer node key/value pair to the given json
*
* @param json
*/
protected void addEarthexplorerNode(JSONObject json) {
json.put(NODE_KEY, EARTHEXPLORER_NODE_VALUE);
}
/** /**
* Adds the given api key value to the given json. * Adds the given api key value to the given json.
* *
......
...@@ -7,7 +7,10 @@ import de.potsdam.gfz.usgsapi.json.response.LoginResponse; ...@@ -7,7 +7,10 @@ import de.potsdam.gfz.usgsapi.json.response.LoginResponse;
import net.minidev.json.JSONObject; import net.minidev.json.JSONObject;
/** /**
* Represents a login request holding the user credentials * Upon a successful login, an API key will be returned. This key will be active for one hour and should be destroyed upon final use of the service by calling the logout method.
*
* This request requires an HTTP POST request instead of a HTTP GET request as a security measure to prevent username and password information from being logged by firewalls, web
* servers, etc.
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
* *
...@@ -27,6 +30,18 @@ public class LoginRequest extends JSONRequest<LoginResponse> { ...@@ -27,6 +30,18 @@ public class LoginRequest extends JSONRequest<LoginResponse> {
private final String authType; private final String authType;
private final String catalogId; private final String catalogId;
/**
* Ctor
*
* @param username
* - Your USGS registration username
* @param password
* - Your USGS registration password
* @param authType
* - Determines the authotization type
* @param catalogId
* - Determines the dataset catalog to use
*/
public LoginRequest(String username, String password, String authType, String catalogId) { public LoginRequest(String username, String password, String authType, String catalogId) {
super(RequestCode.LOGIN); super(RequestCode.LOGIN);
this.username = username; this.username = username;
...@@ -39,7 +54,9 @@ public class LoginRequest extends JSONRequest<LoginResponse> { ...@@ -39,7 +54,9 @@ public class LoginRequest extends JSONRequest<LoginResponse> {
* Uses default values for authType (=EROS) and catalogId (=EE) * Uses default values for authType (=EROS) and catalogId (=EE)
* *
* @param username * @param username
* - Your USGS registration username
* @param password * @param password
* - Your USGS registration password
*/ */
public LoginRequest(String username, String password) { public LoginRequest(String username, String password) {
this(username, password, DEFAULT_AUTHTYPE_VALUE, DEFAULT_CATALOGID_VALUE); this(username, password, DEFAULT_AUTHTYPE_VALUE, DEFAULT_CATALOGID_VALUE);
......
...@@ -8,7 +8,7 @@ import net.minidev.json.JSONObject; ...@@ -8,7 +8,7 @@ import net.minidev.json.JSONObject;
import net.minidev.json.parser.ParseException; import net.minidev.json.parser.ParseException;
/** /**
* Represents a logout request, invalidating the given apikey. * This method is used to remove the users API key from being used in the future.
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
* *
...@@ -17,6 +17,12 @@ public class LogoutRequest extends JSONRequest<LogoutResponse> { ...@@ -17,6 +17,12 @@ public class LogoutRequest extends JSONRequest<LogoutResponse> {
private final String apiKey; private final String apiKey;
/**
* Ctor
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
*/
public LogoutRequest(String apiKey) { public LogoutRequest(String apiKey) {
super(RequestCode.LOGOUT); super(RequestCode.LOGOUT);
this.apiKey = apiKey; this.apiKey = apiKey;
......
...@@ -13,13 +13,14 @@ import net.minidev.json.JSONObject; ...@@ -13,13 +13,14 @@ import net.minidev.json.JSONObject;
import net.minidev.json.parser.ParseException; import net.minidev.json.parser.ParseException;
/** /**
* Represents a hits request, returning the number of expected hits.<br>
* <br>
* Searching is done with limited search criteria. All coordinates are assumed decimal-degree format. If lowerLeft or upperRight are supplied, then both must exist in the request * Searching is done with limited search criteria. All coordinates are assumed decimal-degree format. If lowerLeft or upperRight are supplied, then both must exist in the request
* to complete the bounding box. Starting and ending dates, if supplied, are used as a range to search data based on acquisition dates. The current implementation will only search * to complete the bounding box. Starting and ending dates, if supplied, are used as a range to search data based on acquisition dates. The current implementation will only search
* at the date level, discarding any time information. If data in a given dataset is composite data, or data acquired over multiple days, a search will be done to match any * at the date level, discarding any time information. If data in a given dataset is composite data, or data acquired over multiple days, a search will be done to match any
* intersection of the acquisition range. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter * intersection of the acquisition range. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter
* timeouts for large result sets for some datasets. * timeouts for large result sets for some datasets.<br>
* <br>
* To use the additional criteria field, pass one of the four search filter objects (SearchFilterAnd, SearchFilterBetween, SearchFilterOr, SearchFilterValue) in JSON format with
* additionalCriteria being the root element of the object.
* *
* *
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de) * @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
...@@ -36,11 +37,17 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc ...@@ -36,11 +37,17 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc
/** /**
* *
* @param apiKey * @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName * @param datasetName
* - name of the dataset, e.g. obtained from {@link DatasetSearchRequest}, like LANDSAT_8_C1
* @param temporalFilter * @param temporalFilter
* - temporal filter range
* @param spatialFilter * @param spatialFilter
* - spatial filter range
* @param filter * @param filter
* - additional filters
* @param includeUnknownCloudCover * @param includeUnknownCloudCover
* - flag for also include scenes with unknown cloud cover
*/ */
public SceneSearchRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, SearchFilter filter, Integer minCloudCover, public SceneSearchRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, SearchFilter filter, Integer minCloudCover,
Integer maxCloudCover, Boolean includeUnknownCloudCover) { Integer maxCloudCover, Boolean includeUnknownCloudCover) {
...@@ -51,10 +58,22 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc ...@@ -51,10 +58,22 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc
this.includeUnknownCloudCover = includeUnknownCloudCover; this.includeUnknownCloudCover = includeUnknownCloudCover;
} }
/**
* Returns the received search results
*
* @return
*/
public SearchResultOptions getSearchResultOptions() { public SearchResultOptions getSearchResultOptions() {
return resultOptions; return resultOptions;
} }
/**
* updates this request
*
* @param maxResult
* @param startingNumber
* @param sortOrder
*/
public void updateSearchResultOptions(int maxResult, int startingNumber, SortOrder sortOrder) { public void updateSearchResultOptions(int maxResult, int startingNumber, SortOrder sortOrder) {
resultOptions.maxResults = maxResult; resultOptions.maxResults = maxResult;
resultOptions.startingNumber = startingNumber; resultOptions.startingNumber = startingNumber;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment