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).
Method name |
Description |
---|---|
This method adds the HTTP header to be set when a URL call is executed. |
|
This method adds the parameter to be set when a URL call is executed. |
|
This method executes a URL call. |
|
This method sets basic authentication information. |
|
This method sets the method to be used to execute a URL call. |
|
This method sets the content to be sent when a URL call is executed by using the POST method. |
|
This method sets the type of content to be sent when a URL call is executed by using the POST method. |
|
This method sets the proxy to be used when a URL call is executed. |
|
This method sets the type of return message from the server when a URL call is executed. |
|
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:
-
When the HTTP header is specified by the addHeader method or the setAuthentication method, the setting is specified in the HTTP header.
-
If the method set by the setMethod method is RestClient-instance.METHOD_POST, the following processing is performed:
-
When content is specified by the setPostContent method
The content to be sent is set, and the value specified by the setPostContentType method is set as the content type.
-
When content is not specified by the setPostContent method
The parameter specified by the addParameter method is set as content.
-
-
When the method specified by the setMethod method is RestClient-instance.METHOD_GET, the parameter specified by the addParameter method is set as content.
-
The called URL specified by the setUrl method is executed with the method specified by the setMethod method, and a return message is acquired.
-
If the return message type specified by the setReturnType method is RestClient-instance.RETURNTYPE_JSON, the return message is parsed assuming that it is JavaScript-formatted, and the result is returned as the JSON object type.
-
If the return message type specified by the setReturnType method is RestClient-instance.RETURNTYPE_XML, the return message is parsed assuming that it is XML-formatted, and the result is returned as the org.w3c.dom.Document type.
(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