# Smart Card Shell

- - Home
- - GPError
  - GPSystem
  - ByteString
  - ByteBuffer
  - TLV
  - TLVList
  - Card
  - Atr
  - Key
  - Crypto
  - Application
  - GPApplication
  - GPSecDomain
- - ASN1
  - CardFile
  - IsoSecureChannel
  - ApplFactory
  - GPXML
  - JsScript
  - CardSim
- - X509
  - CRL
  - KeyStore
  - Signed CMS
  - Enveloped CMS
  - CMS Generator
  - XMLSignature
  - SSS
  - OCSPQuery
  - LDAP
  - SOAP
  - URLConnection
- - PKCS11Provider
  - PKCS11Session
  - PKCS11Object
- - OutlineNode
  - Dialog
  - Task
- - Tools
  - Modules
- - OpenSCDP

# 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

- URLConnection() constructor
- setConnectTimeout()
- setReadTimeout()
- setTLSKeyStores()
- addHeaderField()
- getHeaderField()
- getHeaderFieldList()
- get()
- getBinary()
- post()
- postBinary()
- put()
- deleteResource()
- toString()

## 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 - 2024 CardContact Systems GmbH , Minden, Germany