ServiceArgumentsParser.java
/*
** Module : ServiceArgumentsParser.java
** Abstract : Base class to interpret input arguments for a web service (REST or SOAP).
**
** Copyright (c) 2020-2022, Golden Code Development Corporation.
**
** -#- -I- --Date-- ---------------------------------------Description----------------------------------------
** 001 CA 20200514 First version.
** CA 20200528 Added APIs for REST extent arguments (not implemented yet).
** 002 CA 20211112 Refactored to allow transfer of the DATASET or TABLE via XML, for SOAP.
** CA 20220329 Added support for REST services written directly in Java.
*/
/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU Affero General Public License for more details.
**
** You may find a copy of the GNU Affero GPL version 3 at the following
** location: https://www.gnu.org/licenses/agpl-3.0.en.html
**
** Additional terms under GNU Affero GPL version 3 section 7:
**
** Under Section 7 of the GNU Affero GPL version 3, the following additional
** terms apply to the works covered under the License. These additional terms
** are non-permissive additional terms allowed under Section 7 of the GNU
** Affero GPL version 3 and may not be removed by you.
**
** 0. Attribution Requirement.
**
** You must preserve all legal notices or author attributions in the covered
** work or Appropriate Legal Notices displayed by works containing the covered
** work. You may not remove from the covered work any author or developer
** credit already included within the covered work.
**
** 1. No License To Use Trademarks.
**
** This license does not grant any license or rights to use the trademarks
** Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
** of Golden Code Development Corporation. You are not authorized to use the
** name Golden Code, FWD, or the names of any author or contributor, for
** publicity purposes without written authorization.
**
** 2. No Misrepresentation of Affiliation.
**
** You may not represent yourself as Golden Code Development Corporation or FWD.
**
** You may not represent yourself for publicity purposes as associated with
** Golden Code Development Corporation, FWD, or any author or contributor to
** the covered work, without written authorization.
**
** 3. No Misrepresentation of Source or Origin.
**
** You may not represent the covered work as solely your work. All modified
** versions of the covered work must be marked in a reasonable way to make it
** clear that the modified work is not originating from Golden Code Development
** Corporation or FWD. All modified versions must contain the notices of
** attribution required in this license.
*/
package com.goldencode.p2j.rest;
import java.io.*;
import javax.servlet.http.*;
import com.goldencode.p2j.main.*;
import com.goldencode.p2j.persist.*;
import com.goldencode.p2j.util.*;
/**
* Base class for parsing the input arguments for a web service call (REST or SOAP).
*/
public abstract class ServiceArgumentsParser
{
/**
* Parse an extent argument.
*
* @param body
* The HTTP body.
* @param request
* The request payload.
* @param idx
* The argument's index.
* @param source
* The arguments's source.
* @param type
* The arguments's type.
* @param extent
* The arguments's length.
*
* @return An array with the argument's values.
*/
protected abstract Object[] parseExtentArgument(String body,
HttpServletRequest request,
int idx,
String source,
String type,
int extent)
throws RequestArgumentError;
/**
* Assign the given argument to the specified value.
*
* @param idx
* The argument's index.
* @param bdt
* The argument's {@link BaseDataType} instance (may be <code>null</code>).
* @param sval
* The string representation of this argument.
*/
protected abstract void assignArgument(int idx, BaseDataType bdt, String sval)
throws RequestArgumentError;
/**
* Parse the argument, by interpreting the request.
*
* @param body
* The request body.
* @param source
* The parameter's encoded source.
* @param request
* The request payload.
*
* @return The resolved argument.
*/
protected abstract String parseArgumentInt(String body, String source, HttpServletRequest request)
throws IOException;
/**
* Load the specified table.
*
* @param content
* The table definition.
*
* @return A {@link TableWrapper} instance to be passed as argument to the remote call.
*/
protected abstract TableWrapper loadTable(String content)
throws IOException,
RequestArgumentError;
/**
* Load the specified dataset.
*
* @param content
* The dataset definition.
*
* @return A {@link DatasetWrapper} instance to be passed as argument to the remote call.
*/
protected abstract DatasetWrapper loadDataSet(String content)
throws IOException,
RequestArgumentError;
/**
* Create a new {@link DatasetWrapper}. This implementation by default returns <code>null</code>.
*
* @param name
* The dataset name.
* @param input
* The INPUT mode.
* @param output
* The OUTPUT mode.
* @param asHandle
* Flag indicating if this is a DATASET-HANDLE parameter.
*
* @return <code>null</code> by default.
*/
protected DatasetWrapper createDataset(String name, boolean input, boolean output, boolean asHandle)
{
return null;
}
/**
* Create a new {@link TableWrapper}. This implementation by default returns <code>null</code>.
*
* @param name
* The table name.
* @param input
* The INPUT mode.
* @param output
* The OUTPUT mode.
* @param asHandle
* Flag indicating if this is a DATASET-HANDLE parameter.
*
* @return <code>null</code> by default.
*/
protected TableWrapper createTable(String name, boolean input, boolean output, boolean asHandle)
{
return null;
}
/**
* Parse the arguments, by interpreting the request.
* <p>
* For OUTPUT, they will be set to default value. For INPUT, they will be resolved from
* the request.
*
* @param service
* The service definition.
* @param request
* The request payload.
*
* @return The resolved arguments.
*/
public final Object[] parseArguments(RestService service, HttpServletRequest request)
throws IOException,
RequestArgumentError
{
LegacyServiceParameter[] serviceParameters = service.ls.parameters();
LegacyServiceParameter[] original = service.getDefinitionParameters();
ArgumentsParser parser = service.getParser(this);
return parseArguments(parser, serviceParameters, original, request);
}
/**
* Parse the arguments, by interpreting the request.
* <p>
* For OUTPUT, they will be set to default value. For INPUT, they will be resolved from
* the request.
*
* @param serviceParameters
* The legacy service definition parameters.
* @param original
* The definition parameters.
* @param request
* The request payload.
*
* @return The resolved arguments.
*/
public final Object[] parseArguments(LegacyServiceParameter[] serviceParameters,
LegacyServiceParameter[] original,
HttpServletRequest request)
throws IOException,
RequestArgumentError
{
return parseArguments(new LegacyArgumentsParser(this), serviceParameters, original, request);
}
/**
* Parse the arguments, by interpreting the request.
* <p>
* For OUTPUT, they will be set to default value. For INPUT, they will be resolved from
* the request.
*
* @param parser
* The parser to be used for parsing the arguments
* @param serviceParameters
* The legacy service definition parameters.
* @param original
* The definition parameters.
* @param request
* The request payload.
*
* @return The resolved arguments.
*/
public final Object[] parseArguments(ArgumentsParser parser,
LegacyServiceParameter[] serviceParameters,
LegacyServiceParameter[] original,
HttpServletRequest request)
throws IOException,
RequestArgumentError
{
byte[] bbody = LegacyServiceHandler.readBody(request);
String body = new String(bbody);
Object[] args = new Object[original.length];
for (int i = 0; i < args.length; i++)
{
LegacyServiceParameter lsp = original[i];
args[i] = parser.initArgument(lsp, serviceParameters, i);
}
for (int i = 0; i < serviceParameters.length; i++)
{
LegacyServiceParameter lsp = serviceParameters[i];
if (lsp.returnValue())
{
continue;
}
if (lsp.input())
{
int idx = lsp.ordinal() - 1;
Object arg = parser.parseArgument(lsp, original, args[idx], i, body, request);
args[idx] = arg;
}
}
return args;
}
/**
* Raises an error so that the request stops with a 5xx internal server error.
*
* @param bdt
* The BDT for which the value could not be parsed.
* @param val
* The attempted value to assign.
*/
protected void notAValue(BaseDataType bdt, String val)
throws RequestArgumentError
{
String msg = "The value was not a " + bdt.getTypeName();
switch (bdt.getClass().getSimpleName())
{
case "decimal":
msg = "Unable to convert from java.lang.String to java.math.BigDecimal - The value was not a DECIMAL";
break;
case "integer":
msg = "Unable to convert from java.lang.String to java.lang.Integer - The value was not an INTEGER";
break;
case "int64":
msg = "Unable to convert from java.lang.String to java.lang.Long - The value was not a LONG";
break;
case "date":
case "datetime":
case "datetimetz":
msg = "Unable to convert from java.lang.String to java.util.GregorianCalendar - The value was not a DATE, DATETIME or DATETIME-TZ";
break;
case "rowid":
// TODO: what is the correct message?
msg = "The value was not a Rowid";
break;
case "memptr":
// TODO: what is the correct message?
msg = "The value was not a Memptr";
break;
}
throw new RequestArgumentError(msg);
}
/**
* Generate an unknown instance for the given type.
*
* @param type
* The parameter's type.
*
* @return The unknown instance.
*/
BaseDataType unknownInstance(String type)
{
return BaseDataType.generateUnknown(BaseDataType.fromTypeName(type));
}
}