Scripting Server

URLConnection - Reference Documentation

Class implementing an URL connection to a resource. This class can be used to put, get, post or delete local and remote resources (CRUD operations).

Index of Methods

Properties

Type Name Description
Number responseCode The HTTP response code
String responseMessage The HTTP response message
X509[] serverCertificates The certificate chain returned by the server in a TLS connection. The server certificate is the first element
String contentEncoding The encoding format for the content
String contentLength The length of the content
String contentType The content type
Date date The date form the header field
Date expiration The expiration from the header field
Date lastModified The date of last modification from the header field

Constructor

Prototype

URLConnection(String url)

Description

Create a connection object to access a resource identified by the URL.

Arguments

Type Name Description
String url URL of the resource to access

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var cwd = GPSystem.mapFilename("urltest.dat", GPSystem.CWD);

var urlConnection = new URLConnection("file:" + cwd);

setConnectTimeout()

Prototype

void setConnectTimeout(Number ms)

Description

Sets the number of milliseconds to wait for a connect to the remote system.

Arguments

Type Name Description
Number ms The timeout in milliseconds

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


urlConnection.setConnectTimeout(10000);		// 10 seconds

setReadTimeout()

Prototype

void setReadTimeout(Number ms)

Description

Sets the number of milliseconds to wait for a response from the remote system.

Arguments

Type Name Description
Number ms The timeout in milliseconds

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


urlConnection.setReadTimeout(10000);		// 10 seconds

setTLSKeyStores()

Prototype

void setTLSKeyStores(KeyStore truststore, KeyStore keystore, String keypassword)

Description

Sets the key stores to be used for TLS connections.

The trust store contains CA certificates that can be used to verify the server certificate.

The key store contains the private key, certificate and CA certificates to be used for TLS client authentication.

Setting a TLS key store only has an effect for connections using transport layer security (e.g. https).

Arguments

Type Name Description
KeyStore truststore The keystore containing trusted certificates for server authentication
KeyStore keystore An optional key store containing the private key and certificates for TLS client authentication
String keypassword The password to recover the private key

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var truststore = new KeyStore("SUN", "jks", "truststore", "openscdp");
var keystore = new KeyStore("SUN", "jks", "clientkeystore", "openscdp");

var urlConnection = new URLConnection("https://localhost:8443");

urlConnection.setTLSKeyStores(truststore, keystore, "openscdp");

var page = urlConnection.get();

addHeaderField()

Prototype

void addHeaderField(String fieldName, String value)

Description

Add a HTTP header field to the request.

If the field does already exists, then a further element is added.

Arguments

Type Name Description
String fieldName The HTTP header field name
Number ms The field value

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


urlConnection.addHeaderField("x-my-header", "My private header field");

getHeaderField()

Prototype

String[] getHeaderField(String fieldName)

Description

Returns a list of values for given header field.

If the field does already exists, then undefined is returned

Arguments

Type Name Description
String fieldName The HTTP header field name

Return

String[] The list of values for this header field

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


urlConnection.getHeaderField("x-my-header");

getHeaderFieldList()

Prototype

String[] getHeaderFieldList()

Description

Returns a list of header fields contained in the response.

Return

String[] The list of header fields

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


urlConnection.getHeaderFieldList();

get()

Prototype

String get()

Description

Read from the resource the full content as string.

Return

String The content of the resource as string

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var urlConnection = new URLConnection("file:" + cwd);
var page = urlConnection.get();
assert(page.equals("Hello World\n"));

getBinary()

Prototype

ByteString getBinary()

ByteString getAsByteString()

Description

Read from the resource the full content as binary content.

Return

ByteString The content of the resource as bytestring

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var urlConnection = new URLConnection("file:" + cwd);
var page = urlConnection.getAsByteString();
assert(page.equals(new ByteString("48656C6C6F20576F726C640D0A", HEX)));

post()

Prototype

String post(String str)

Description

Write the text to the resource and receive response.

Arguments

Type Name Description
String str The content to write

Return

String The content of the resource as string

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var url = "http://localhost:8080/";
var urlConnection = new URLConnection(url + "admin?restart");

urlConnection.addHeaderField("x-my-header", "My private header field");

var page = urlConnection.get();
print("GET:\n" + page);
print(urlConnection.responseCode + " - " + urlConnection.responseMessage);
print("ContentEncoding : " + urlConnection.contentEncoding);
print("ContentLength : " + urlConnection.contentLength);
print("ContentType : " + urlConnection.contentType);
print("Date : " + urlConnection.date);
print("Expiration : " + urlConnection.expiration);
print("Last Modified : " + urlConnection.lastModified);
var hl = urlConnection.getHeaderFieldList();
print("Header field list : " + hl);
for each (var s in hl) {
	var v = urlConnection.getHeaderField(s);
	print(s + " : " + v);
}

assert(urlConnection.responseCode == 200);


var urlConnection = new URLConnection(url + "admin");

var script = "GPSystem.trace(\"Hello World\");\n";

var result = urlConnection.post(script);
print("POST:\n" + result);

var result = urlConnection.post(script);
print("POST:\n" + result);


var urlConnection = new URLConnection(url + "admin");

var page = urlConnection.get();
print("GET:\n" + page);

postBinary()

Prototype

ByteString post(ByteString data)

Description

Write binary data to the resource and receive response.

Arguments

Type Name Description
ByteString data The content to write

Return

ByteString The content of the resource as ByteString

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var url = "http://localhost:8080/";
var urlConnection = new URLConnection(url + "admin?restart");

var urlConnection = new URLConnection(url + "admin");

var script = 
"function handleRequest(req, res) {\n" +
"var cl = req.contentLength;\n" + 
"print(cl);\n" +
"var is = req.getEntityAsInputStream();\n" +
"var bs = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, cl);\n" +
"is.read(bs);\n" +
"var bb = new ByteBuffer(bs);\n" +
"print(bb.toByteString());\n" +
"res.setContentLength(3);\n" +
"res.write(new ByteString(\"Yes\", ASCII));\n" +
"}\n";



var result = urlConnection.post(script);
print("POST:\n" + result);

var urlConnection = new URLConnection(url + "se");

var data = new ByteString("Hello World", ASCII);
var result = urlConnection.postBinary(data);

assert(result.toString(ASCII) == "Yes");

put()

Prototype

String put(String str)

Description

Write the text to the resource and receive response.

Arguments

Type Name Description
String str The content to write

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var url = "http://localhost:8080/";
var urlConnection = new URLConnection(url + "admin?restart");

var page = urlConnection.get();
print("GET:\n" + page);


var urlConnection = new URLConnection(url + "admin");

var script = "GPSystem.trace(\"Hello World\");\n";

var result = urlConnection.put(script);
print("PUT:\n" + result);

var result = urlConnection.put(script);
print("PUT:\n" + result);


var urlConnection = new URLConnection(url + "admin");

var page = urlConnection.get();
print("GET:\n" + page);

deleteResource()

Prototype

void deleteResource()

Description

Delete the resource.

The delete operation only works for connections using HTTP.

The method is not named "delete" because delete is a reserved name in the Rhino JavaScript implementation.

Return

Exceptions

Name Value Description
GPError GPError.ARGUMENTS_MISSING Too few arguments in call
GPError GPError.INVALID_ARGUMENTS Too many arguments in call
GPError GPError.INVALID_TYPE Type of argument is invalid for call

Example


var url = "http://localhost:8080/";

var urlConnection = new URLConnection(url + "admin");

urlConnection.deleteResource();

toString()

Prototype

String toString()

Description

Return the URL as string

Return

String The URL

Exceptions

Name Value Description

Example


assert(urlConnection.toString() == url + "admin");

© Copyright 2003 - 2020 CardContact Systems GmbH , Minden, Germany