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

extended javadoc

parent fab5c602
......@@ -47,18 +47,7 @@ public class CloudCoverUpdateFromMetadataUrl {
private static final Random rand = new Random();
public static void main(String[] args) throws Exception {
// landsat_tm(108), landsat_mss(107), landsat_8(104), landsat_7(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);
short datasetids[] = new short[] { 250 }; // , 108, 107, 112 };
final SceneDatabase db = SceneDatabase.getInstance();
ExecutorService pool = Executors.newFixedThreadPool(20);
......
......@@ -8,11 +8,16 @@ import de.potsdam.gfz.usgsapi.json.datamodels.TemporalFilter;
import de.potsdam.gfz.usgsapi.json.response.JSONResponse;
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> {
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 SPATIAL_FILTER_KEY = "spatialFilter";
private static final String INCLUDE_UNKNOWN_CLOUDCOVER_KEY = "includeUnknownCloudCover";
......
......@@ -12,10 +12,9 @@ import net.minidev.json.parser.ParseException;
/**
* Represents a dataset search request.<br>
* <br>
* This method is used to find datasets available for searching. By passing no parameters except node, all available datasets are returned.
* Additional parameters such as temporal range and 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 value against the public dataset name with
* assumed wildcards at the beginning and end.
* 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
* 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
* value against the public dataset name with assumed wildcards at the beginning and end.
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
*
......@@ -26,13 +25,14 @@ public class DatasetSearchRequest extends AbstractSearchRequest<DatasetSearchRes
private Boolean publicOnly = null;
/**
* @param code
* Ctor
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
* @param datasetName
* @param startDate
* @param endDate
* @param lowerLeft
* @param upperRight
* @param temporalFilter
* @param spatialFilter
* @param publicOnly
*/
public DatasetSearchRequest(String apiKey, String datasetName, TemporalFilter temporalFilter, SpatialFilter spatialFilter, Boolean publicOnly) {
super(RequestCode.DATASETS, apiKey);
......
......@@ -30,6 +30,18 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse>
private final String[] entityIds;
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) {
super(RequestCode.DOWNLOADOPTIONS);
this.apiKey = apiKey;
......@@ -38,6 +50,16 @@ public class DownloadOptionsRequest extends JSONRequest<DownloadOptionsResponse>
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) {
this(apiKey, datasetName, entityIds, DEFAULT_MACHINE_ONLY_VALUE);
}
......
......@@ -3,6 +3,7 @@
*/
package de.potsdam.gfz.usgsapi.json.request;
import de.potsdam.gfz.usgsapi.json.response.DownloadOptionsResponse;
import de.potsdam.gfz.usgsapi.json.response.DownloadResponse;
import net.minidev.json.JSONArray;
import net.minidev.json.JSONObject;
......@@ -12,10 +13,9 @@ import net.minidev.json.parser.ParseException;
* Represents a download request.<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
* products are automatically excluded from the response.<br>
* <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
* the data before submitting subsequent requests. The rate limit is defined by 10 unattampted downloads within the last 10 minutes.
* products are automatically excluded from the response.
*
* This request implements a rate limit based on a limit of 10 downloads that have not been completed within the last 15 minutes.
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
*
......@@ -39,6 +39,21 @@ public class DownloadRequest extends JSONRequest<DownloadResponse> {
private final String dataUse;
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) {
super(RequestCode.DOWNLOAD);
this.apiKey = apiKey;
......@@ -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
* - 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
*
*/
public DownloadRequest(String apiKey, String datasetName, String[] entityIds) {
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;
import net.minidev.json.parser.ParseException;
/**
* Represents a hits request, returning the number of expected hits.<br>
* <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,
* 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.
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
......@@ -24,11 +21,17 @@ public class HitsRequest extends AbstractFilteredSearchRequest<HitsResponse> {
/**
*
* @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 temporalFilter
* - temporal filter range
* @param spatialFilter
* - spatial filter range
* @param filter
* - additional filters
* @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,
Integer maxCloudCover, Boolean includeUnknownCloudCover) {
......
......@@ -8,14 +8,13 @@ import net.minidev.json.JSONObject;
import net.minidev.json.parser.ParseException;
/**
* Abstract base class for all requests
*
* @author Daniel Eggert (daniel.eggert@gfz-potsdam.de)
*
*/
public abstract class JSONRequest<T extends JSONResponse> {
private static final String NODE_KEY = "node";
private static final String EARTHEXPLORER_NODE_VALUE = "EE";
private static final String APIKEY_KEY = "apiKey";
private static final String LATITUDE_KEY = "latitude";
......@@ -50,15 +49,6 @@ public abstract class JSONRequest<T extends JSONResponse> {
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.
*
......
......@@ -7,7 +7,10 @@ import de.potsdam.gfz.usgsapi.json.response.LoginResponse;
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)
*
......@@ -27,6 +30,18 @@ public class LoginRequest extends JSONRequest<LoginResponse> {
private final String authType;
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) {
super(RequestCode.LOGIN);
this.username = username;
......@@ -39,7 +54,9 @@ public class LoginRequest extends JSONRequest<LoginResponse> {
* Uses default values for authType (=EROS) and catalogId (=EE)
*
* @param username
* - Your USGS registration username
* @param password
* - Your USGS registration password
*/
public LoginRequest(String username, String password) {
this(username, password, DEFAULT_AUTHTYPE_VALUE, DEFAULT_CATALOGID_VALUE);
......
......@@ -8,7 +8,7 @@ import net.minidev.json.JSONObject;
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)
*
......@@ -17,6 +17,12 @@ public class LogoutRequest extends JSONRequest<LogoutResponse> {
private final String apiKey;
/**
* Ctor
*
* @param apiKey
* - api key string acquired via {@link LoginRequest}
*/
public LogoutRequest(String apiKey) {
super(RequestCode.LOGOUT);
this.apiKey = apiKey;
......
......@@ -13,13 +13,14 @@ import net.minidev.json.JSONObject;
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
* 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
* 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)
......@@ -36,11 +37,17 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc
/**
*
* @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 temporalFilter
* - temporal filter range
* @param spatialFilter
* - spatial filter range
* @param filter
* - additional filters
* @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,
Integer maxCloudCover, Boolean includeUnknownCloudCover) {
......@@ -51,10 +58,22 @@ public class SceneSearchRequest extends AbstractFilteredSearchRequest<SceneSearc
this.includeUnknownCloudCover = includeUnknownCloudCover;
}
/**
* Returns the received search results
*
* @return
*/
public SearchResultOptions getSearchResultOptions() {
return resultOptions;
}
/**
* updates this request
*
* @param maxResult
* @param startingNumber
* @param sortOrder
*/
public void updateSearchResultOptions(int maxResult, int startingNumber, SortOrder sortOrder) {
resultOptions.maxResults = maxResult;
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