| @@ -11,20 +11,11 @@ |
| */ |
| package csip; |
| |
| -import com.fasterxml.uuid.Generators; |
| -import static csip.Config.CSIP_ARCHIVE_FAILEDONLY; |
| -import static csip.Config.CSIP_DIR; |
| -import static csip.Config.CSIP_KEEPWORKSPACE; |
| -import static csip.Config.CSIP_LOGGING_STRMAX; |
| -import static csip.Config.CSIP_RESPONSE_STACKTRACE; |
| -import static csip.Config.CSIP_SNAPSHOT; |
| -import static csip.Config.CSIP_TIMEZONE; |
| -import static csip.Config.CSIP_VERSION; |
| +import static csip.Config.*; |
| import csip.annotations.*; |
| - |
| import csip.utils.*; |
| import csip.utils.Services.FormDataParameter; |
| - |
| +import com.fasterxml.uuid.Generators; |
| import java.io.*; |
| import java.net.URI; |
| import java.sql.Connection; |
| @@ -50,6 +41,20 @@ |
| * Base class for all modeling and data services. |
| * |
| * A service implementation will subclass ModelDataService. |
| + * <br> |
| + * <br> |
| + * Example:<br> |
| + * <pre> |
| + * import csip.ModelDataService; |
| + * |
| + * @Path("m/myservice/1.0") |
| + * public class MyService extends ModelDataService { |
| + * |
| + * public void doProcess() { |
| + * // service implementation. |
| + * } |
| + * } |
| + * </pre> |
| * |
| * @author Olaf David |
| */ |
| @@ -81,7 +86,7 @@ |
| public static final String KEY_TSTAMP = "tstamp"; //? |
| public static final String KEY_TZ = "tz"; // timezone |
| public static final String KEY_PROGRESS = "progress"; |
| - public static final String KEY_STATE = "state"; |
| + public static final String KEY_STAGE = "stage"; |
| |
| // parameter keys |
| public static final String KEY_NAME = "name"; |
| @@ -173,7 +178,7 @@ |
| // The progress (message) during execution. |
| private String progress = null; |
| |
| - private String state = null; |
| + private String stage = null; |
| |
| // file stuff |
| private List<File> fres; |
| @@ -385,8 +390,8 @@ |
| * |
| * @return the state, or null if not defined. |
| */ |
| - private final String getState() { |
| - return Utils.getServiceState(getClass()); |
| + private final String getStage() { |
| + return Utils.getServiceStage(getClass()); |
| } |
| |
| |
| @@ -447,7 +452,8 @@ |
| |
| /** |
| * workflow step 1: process the request data. |
| - * @throws Exception |
| + * |
| + * @throws Exception if pre-processing fails. |
| */ |
| protected void preProcess() throws Exception { |
| } |
| @@ -455,7 +461,8 @@ |
| |
| /** |
| * workflow step 2: The process method. |
| - * @throws Exception |
| + * |
| + * @throws Exception if processing fails. |
| */ |
| protected void doProcess() throws Exception { |
| } |
| @@ -463,7 +470,7 @@ |
| |
| /** |
| * workflow step 3: create the response the data. |
| - * @throws Exception |
| + * @throws Exception if post-processing fails. |
| */ |
| protected void postProcess() throws Exception { |
| } |
| @@ -495,7 +502,7 @@ |
| * Process logic of the service. |
| * @return null if the process ended successfully, the error message |
| * otherwise. |
| - * @throws Exception |
| + * @throws Exception if processing fails. |
| * @deprecated use doProcess() instead. |
| */ |
| @Deprecated |
| @@ -507,9 +514,9 @@ |
| /** |
| * This replaces the process() call from process0 |
| */ |
| - private Throwable doProcessWrapper(int phase) { |
| + private Throwable doProcessWrapper(int execPhase) { |
| try { |
| - switch (phase) { |
| + switch (execPhase) { |
| case PRE: |
| preProcess(); |
| break; |
| @@ -624,7 +631,7 @@ |
| /** |
| * Step 4: Create the results as JSON, (deprecated) |
| * @return the results as an array of JSON objects. |
| - * @throws Exception |
| + * @throws Exception if result creation fails |
| * @deprecated replaced by {@link #postProcess()} |
| */ |
| @Deprecated |
| @@ -636,7 +643,7 @@ |
| /** |
| * Create a report. |
| * @return The report content as JSONArray |
| - * @throws Exception |
| + * @throws Exception if report generation fails. |
| * @deprecated replaced by {@link #report()} |
| */ |
| @Deprecated |
| @@ -648,7 +655,7 @@ |
| /** |
| * Create a report. |
| * |
| - * @throws Exception |
| + * @throws Exception if report creation fails. |
| */ |
| protected void report() throws Exception { |
| } |
| @@ -700,7 +707,7 @@ |
| /** |
| * Get a file from the workspace. You can specify workspace sub-folders in |
| * the name (use always a slash as file separator). |
| - * @param name |
| + * @param name the file name |
| * @return A file object from the workspace. |
| */ |
| protected final File getWorkspaceFile(String name) { |
| @@ -754,7 +761,7 @@ |
| |
| /** |
| * Set the request metainfo. |
| - * @param mi |
| + * @param mi the new metainfo |
| * @deprecated |
| */ |
| @Deprecated |
| @@ -765,7 +772,7 @@ |
| |
| /** |
| * Set the request parameter. |
| - * @param parameter |
| + * @param parameter the parameter |
| * @deprecated |
| */ |
| @Deprecated |
| @@ -776,7 +783,7 @@ |
| |
| /** |
| * Set the request |
| - * @param req |
| + * @param req the request object. |
| * @deprecated |
| */ |
| @Deprecated |
| @@ -787,6 +794,7 @@ |
| |
| /** |
| * Set the Parameter map |
| + * @param pm the parameter map. |
| * @deprecated |
| */ |
| @Deprecated |
| @@ -818,7 +826,7 @@ |
| * Get the metainfo value as String. |
| * @param name the name of the metainfo entry |
| * @return the value of a metainfo entry |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected String getStringMetainfo(String name) throws ServiceException { |
| try { |
| @@ -833,7 +841,7 @@ |
| * Get metainfo value as int. |
| * @param name the name of the metainfo entry |
| * @return the int value of a metainfo entry. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected int getIntMetainfo(String name) throws ServiceException { |
| try { |
| @@ -848,7 +856,7 @@ |
| * Get the metainfo value as double. |
| * @param name the name of the metainfo entry |
| * @return the metainfo value. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected double getDoubleMetainfo(String name) throws ServiceException { |
| try { |
| @@ -863,7 +871,7 @@ |
| * Get a metainfo value as boolean |
| * @param name the name of the metainfo entry |
| * @return the metainfo value |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean getBooleanMetainfo(String name) throws ServiceException { |
| try { |
| @@ -958,7 +966,7 @@ |
| * |
| * @param name the file name |
| * @return true if the file exist, false otherwise |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean hasFileInput(String name) throws ServiceException { |
| return getFileInput(name) != null; |
| @@ -970,7 +978,7 @@ |
| * @param name the file name (no path) |
| * @return the file object with its absolute file path within the workspace. |
| * It returns null if the file is not input or does not exist. |
| - * @throws csip.ServiceException |
| + * @throws csip.ServiceException if the file is missing |
| */ |
| protected File getFileInput(String name) throws ServiceException { |
| if (!Arrays.asList(inputs).contains(name)) { |
| @@ -998,7 +1006,8 @@ |
| /** |
| * Check is a required parameter exists. |
| * |
| - * @param name |
| + * @param name the parameter name |
| + * @throws ServiceException if the parameter is not found. |
| */ |
| protected void requiredParam(String name) throws ServiceException { |
| if (!hasParam(name)) { |
| @@ -1029,7 +1038,7 @@ |
| * Get a String parameter |
| * @param name the parameter name |
| * @return the parameter value as String |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected String getStringParam(String name) throws ServiceException { |
| try { |
| @@ -1045,7 +1054,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if the parameter is missing |
| * @return the value of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected String getStringParam(String name, String def) throws ServiceException { |
| try { |
| @@ -1061,7 +1070,7 @@ |
| * Get an int parameter. |
| * @param name the parameter name |
| * @return the parameter value as int |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected int getIntParam(String name) throws ServiceException { |
| try { |
| @@ -1077,7 +1086,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the int value of the parameter. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected int getIntParam(String name, int def) throws ServiceException { |
| try { |
| @@ -1093,7 +1102,7 @@ |
| * Get an double parameter |
| * @param name the parameter name |
| * @return the parameter value as double |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected double getDoubleParam(String name) throws ServiceException { |
| try { |
| @@ -1109,7 +1118,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the double value of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected double getDoubleParam(String name, double def) throws ServiceException { |
| try { |
| @@ -1125,7 +1134,7 @@ |
| * Get a boolean parameter. |
| * @param name the parameter name. |
| * @return the parameter value as boolean. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean getBooleanParam(String name) throws ServiceException { |
| try { |
| @@ -1141,7 +1150,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value. |
| * @return the boolean value of the parameter. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean getBooleanParam(String name, boolean def) throws ServiceException { |
| try { |
| @@ -1157,7 +1166,7 @@ |
| * Get a long parameter. |
| * @param name the parameter name. |
| * @return the parameter value as long. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected long getLongParam(String name) throws ServiceException { |
| try { |
| @@ -1173,7 +1182,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the long value of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected long getLongParam(String name, long def) throws ServiceException { |
| try { |
| @@ -1189,7 +1198,7 @@ |
| * Get a JSONObject parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected JSONObject getJSONParam(String name) throws ServiceException { |
| try { |
| @@ -1205,7 +1214,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected JSONObject getJSONParam(String name, JSONObject def) throws ServiceException { |
| try { |
| @@ -1221,7 +1230,7 @@ |
| * Get a JSONArray parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected JSONArray getJSONArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1237,7 +1246,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected JSONArray getJSONArrayParam(String name, JSONArray def) throws ServiceException { |
| try { |
| @@ -1253,7 +1262,7 @@ |
| * Get a int[] parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected int[] getIntArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1270,7 +1279,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected int[] getIntArrayParam(String name, int[] def) throws ServiceException { |
| try { |
| @@ -1286,7 +1295,7 @@ |
| * Get a boolean[] parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean[] getBooleanArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1303,7 +1312,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected boolean[] getBooleanArrayParam(String name, boolean[] def) throws ServiceException { |
| try { |
| @@ -1319,7 +1328,7 @@ |
| * Get a long[] parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected long[] getLongArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1336,7 +1345,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected long[] getLongArrayParam(String name, long[] def) throws ServiceException { |
| try { |
| @@ -1352,7 +1361,7 @@ |
| * Get a String[] parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected String[] getStringArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1369,7 +1378,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is a JSON error. |
| */ |
| protected String[] getStringArrayParam(String name, String[] def) throws ServiceException { |
| try { |
| @@ -1385,7 +1394,7 @@ |
| * Get a double[] parameter. |
| * @param name the parameter name. |
| * @return the parameter value as JSONObject. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is no array. |
| */ |
| protected double[] getDoubleArrayParam(String name) throws ServiceException { |
| try { |
| @@ -1402,7 +1411,7 @@ |
| * @param name the name of the parameter |
| * @param def the default value if parameter does not exist |
| * @return the JSONObject of the parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is no array |
| */ |
| protected double[] getDoubleArrayParam(String name, double[] def) throws ServiceException { |
| try { |
| @@ -1418,7 +1427,7 @@ |
| * Get the unit of a parameter. |
| * @param name the parameter name |
| * @return the unit as string, 'null' if there is none. |
| - * @throws ServiceException |
| + * @throws ServiceException if unit is missing |
| */ |
| protected String getParamUnit(String name) throws ServiceException { |
| try { |
| @@ -1433,7 +1442,7 @@ |
| * Get the description of a parameter. |
| * @param name the parameter name |
| * @return the description as string, 'null' if there is none. |
| - * @throws ServiceException |
| + * @throws ServiceException if there is no description. |
| */ |
| protected String getParamDescr(String name) throws ServiceException { |
| try { |
| @@ -1448,7 +1457,7 @@ |
| * Get the geometry of a parameter |
| * @param name the name if the parameter |
| * @return the geometry of a parameter |
| - * @throws ServiceException |
| + * @throws ServiceException if there is no geometry |
| */ |
| protected JSONObject getParamGeometry(String name) throws ServiceException { |
| try { |
| @@ -1479,7 +1488,7 @@ |
| * |
| * @param id the id of the resource. |
| * @return the extracted file within the local file system. |
| - * @throws ServiceException |
| + * @throws ServiceException if file cannot be found or unpacked |
| * @see csip.annotations.Resource |
| */ |
| protected File getResourceFile(String id) throws ServiceException { |
| @@ -1493,7 +1502,7 @@ |
| * |
| * @param id the id of the resource |
| * @return the ProcessExecution for that executable |
| - * @throws ServiceException |
| + * @throws ServiceException if there is no EXE |
| * @see csip.annotations.Resource |
| */ |
| protected Executable getResourceExe(String id) throws ServiceException { |
| @@ -1506,7 +1515,7 @@ |
| * |
| * @param id the id of the resource |
| * @return the JDBC connection. |
| - * @throws ServiceException |
| + * @throws ServiceException if connection fails |
| * @see csip.annotations.Resource |
| */ |
| protected Connection getResourceJDBC(String id) throws ServiceException { |
| @@ -1608,7 +1617,7 @@ |
| * Provide a double as a result. |
| * @param name the result name |
| * @param val the value to store |
| - * @param descr |
| + * @param descr the result description. |
| */ |
| protected void putResult(String name, double val, String descr) { |
| results().put(JSONUtils.dataUnitDesc(name, val, null, descr)); |
| @@ -1884,8 +1893,8 @@ |
| |
| /** |
| * Provide a file with description as a result. |
| - * @param file |
| - * @param descr |
| + * @param file the result file |
| + * @param descr the file description |
| */ |
| protected void putResult(File file, String descr) { |
| putResult(file); |
| @@ -2207,7 +2216,9 @@ |
| //////////////////////////////////////////////////////////////////// HTTP |
| |
| /** |
| - * Describe the service as JSON. (Service endpoint only) |
| + * Describe the service as JSON. (Service endpoint use only) |
| + * |
| + * @param uriInfo the URI Info |
| * @return The service signature as JSON |
| */ |
| @GET |
| @@ -2283,7 +2294,7 @@ |
| if (start == null) { |
| start = new Date(); |
| processOptions(); |
| - state = getState(); |
| + stage = getStage(); |
| } |
| |
| if (LOG.isLoggable(Level.INFO)) { |
| @@ -2515,7 +2526,7 @@ |
| * rest call as the 'progress' entry. |
| * |
| * @param progress a meaningful message |
| - * @throws ServiceException |
| + * @throws ServiceException if there are problems. |
| */ |
| protected void setProgress(String progress) throws ServiceException { |
| this.progress = progress; |
| @@ -2526,7 +2537,7 @@ |
| /** |
| * Set the progress as a numerical value (0..100) |
| * @param progress a value between 0 and 100; |
| - * @throws ServiceException |
| + * @throws ServiceException if progress arguments are out of range |
| */ |
| protected void setProgress(int progress) throws ServiceException { |
| if (progress < 0 || progress > 100) { |
| @@ -2809,22 +2820,22 @@ |
| metainfo.put(KEY_STATUS, status); |
| metainfo.put(KEY_SUUID, suid); |
| metainfo.put(KEY_CLOUD_NODE, Services.LOCAL_IP_ADDR); |
| - metainfo.put(KEY_TSTAMP, Dates.newISOFormat(tz).format(start)); |
| + metainfo.put(KEY_REQ_IP, getRemoteAddr()); |
| metainfo.put(KEY_SERVICE_URL, getRequestURL()); |
| - metainfo.put(KEY_REQ_IP, getRemoteAddr()); |
| + if (stage != null) { |
| + metainfo.put(KEY_STAGE, stage); |
| + } |
| |
| String reqContext = getRequestContext().substring(1); |
| String v = Config.getString(reqContext + ".version"); |
| if (v != null) { |
| metainfo.put(reqContext + ".version", v); |
| } |
| - if (state != null) { |
| - metainfo.put(KEY_STATE, state); |
| - } |
| metainfo.put(CSIP_VERSION, Config.getString(CSIP_VERSION)); |
| if (progress != null) { |
| metainfo.put(KEY_PROGRESS, progress); |
| } |
| + metainfo.put(KEY_TSTAMP, Dates.newISOFormat(tz).format(start)); |
| } catch (JSONException ex) { |
| LOG.log(Level.SEVERE, null, ex); |
| } |