Hitachi

JP1 Version 12 JP1/Navigation Platform Content Editing Guide


5.12.2 RestClient (REST caller class)

RestClient has the following methods. Note that the methods of RestClient cannot be used in JavaScript running on a web browser (on the client-side).

Table 5‒8: Methods of RestClient

Method name

Description

addHeader

This method adds the HTTP header to be set when a URL call is executed.

addParameter

This method adds the parameter to be set when a URL call is executed.

execute

This method executes a URL call.

setAuthentication

This method sets basic authentication information.

setMethod

This method sets the method to be used to execute a URL call.

setPostContent

This method sets the content to be sent when a URL call is executed by using the POST method.

setPostContentType

This method sets the type of content to be sent when a URL call is executed by using the POST method.

setProxy

This method sets the proxy to be used when a URL call is executed.

setReturnType

This method sets the type of return message from the server when a URL call is executed.

setUrl

This method sets the called URL to be used when a URL call is executed.

Organization of this subsection

(1) addHeader method

This method adds the HTTP header to be set when a URL call is executed. The added HTTP header is set when the execute method is executed. Adding a header having the same name as the existing one causes the existing one to be overwritten.

(a) Format

RestClient addHeader(String name, String value);

(b) Arguments

  • name

    This argument specifies the name of the HTTP header to be added when a URL call is executed.

  • value

    This argument specifies the value of the HTTP header to be added when a URL call is executed.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(2) addParameter method

This method adds the parameter to be set when a URL call is executed. The added parameter is set when the execute method is executed. Adding a parameter having the same name as the existing one causes the existing one to be overwritten.

(a) Format

RestClient addParameter(String name, String value);

(b) Arguments

  • name

    This argument specifies the name of the parameter to be added when a URL call is executed.

  • value

    This argument specifies the value of the parameter to be added when a URL call is executed.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(3) execute method

This method executes a URL call.

The following processing is performed when a URL call is executed:

(a) Format

Object execute() throws UCNPUserException;

(b) Arguments

None

(c) Return values

Depending on the type of return message set by the setReturnType method, one of the following values is returned:

  • RestClient-instance.RETURNTYPE_STRING: Character string that is identical to the return message

  • RestClien-instance.RETURNTYPE_JSON: Object type that stores the return message

  • RestClient-instance.RETURNTYPE_XML: org.w3c.dom.Document type that stores the return message

(d) Exception

If an error occurs with this method, the UCNPUserException exception is thrown.

If the javax.ws.rs.WebApplicationException exception is thrown and nested, you can view the details of the error that occurred when the URL was invoked. For details about how to handle the javax.ws.rs.WebApplicationException exception, check the caller API.

A coding example of the exception handling is provided below.

Precondition for the REST server

A JSON-format character string ({"initvalues":{"text1":"30"}}) is returned from the REST server at the called destination.

Overview of exception handling

  • When the call is successful, the value 30 of initvalues.text1 is stored in the variable result.

  • If the error 404 NotFound occurs during the call, the character string Not found is stored in the variable errmsg.

Coding example

var result;
var errmsg = "";
try {
  var client = ucnpJavaScriptPluginManager.getRestClient();
  var json = client.execute();
  result = json.initvalues.text1;
} catch (ex) {
  errmsg = ex;
  if (ex instanceof Java.type("jp.co.hitachi.soft.ucnp.base.common.UCNPUserException")) {
    var ex2 = ex.getCause();
    if (ex2 instanceof Java.type("javax.ws.rs.WebApplicationException")) {
      if (ex2.getResponse().getStatus() == 404) {
        errmsg = "Not found";
      }
    }
  }
}

(4) setAuthentication method

This method sets basic authentication information.

Specify the Authorization HTTP header by using the specified user name and password.

(a) Format

RestClient setAuthentication(String user, String password);

(b) Arguments

  • user

    This argument specifies the name of the user used for basic authentication.

  • password

    This argument specifies the password of the user used for basic authentication.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(5) setMethod method

This method sets the method to be used to execute a URL call.

The method set by default when this method is not called is RestClient-instance.METHOD_GET.

(a) Format

RestClient setMethod(int method);

(b) Arguments

  • method

    One of the following values is specified:

    • RestClient-instance.METHOD_GET: When the GET method is specified

    • RestClient-instance.METHOD_POST: When the POST method is specified

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(6) setPostContent method

This method sets the content to be sent when a URL call is executed by using the POST method.

(a) Format

RestClient setPostContent(String content);

(b) Arguments

  • content

    This argument specifies the content to be sent when a URL call is executed.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(7) setPostContentType method

This method sets the type of content to be sent when a URL call is executed by using the POST method.

The content type set by default when this method is not called is text/json.

(a) Format

RestClient setPostContentType(String type);

(b) Arguments

  • type

    This argument specifies the type of content to be sent when a URL call is executed.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(8) setProxy method

This method sets the proxy to be used when a URL call is executed.

When this method is not invoked, a direct connection is made to the called URL without using a proxy.

(a) Format

RestClient setProxy(String host, int port, String user, String password);

(b) Arguments

  • host

    This argument specifies the host name of the proxy.

  • port

    This argument specifies the port number of the proxy.

  • user

    This argument specifies the name of the user to be specified when authentication is necessary for the proxy. If authentication is not necessary for the proxy, specify null.

  • password

    This argument specifies the password of the user to be specified when authentication is necessary for the proxy. If authentication is not necessary for the proxy, specify null.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(9) setReturnType method

This method sets the type of return message from the server when a URL call is executed.

The type specified with this method determines the interpretation and return value of the return message.

(a) Format

RestClient setReturnType(int type);

(b) Arguments

  • type

    This argument specifies the type of the return message. The following types can be specified for this argument:

    • RestClient-instance.RETURNTYPE_STRING: When the return message type is character string

    • RestClient-instance.RETURNTYPE_JSON: When the return message type is JSON

    • RestClient-instance.RETURNTYPE_XML: When the return message type is XML

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None

(10) setUrl method

This method sets the called URL to be used when a URL call is executed.

If this method is not invoked, the cached value of the JavaScript Plugin #url (the value set in the URL text box in the Attribute Settings window) is set as a default value.

(a) Format

RestClient setUrl(String url);

(b) Arguments

  • url

    This argument specifies the called URL.

(c) Return values

The caller's RestClient object is returned.

(d) Exception

None