UTF8String ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.asn1.ASN1Object
- - iaik.asn1.ASN1String
  - - iaik.asn1.UTF8String

```
public class UTF8String
extends ASN1String
```
This class implements the ASN.1 character string type "UTF8String". UTF8String is a simple ASN.1 string type identified by the UNIVERSAL TAG number 12.
UTF-8 (UCS transformation format 8) is an encoding format that has been developed for handling UCS-2/UCS-4 multi-octet character sets by applications that operate on 7, 8 bit characters. UTF-8 is specified by ISO 10646 in RFC 2279.
RFC 2279 gives an algorithm for transforming UCS-4/UCS-2 multi octet characters into UTF-8 octet sequences. This class can be used for UTF-8 encoding UCS-2/Unicode character strings according to the following rules:
- Characters in the range of 0x0000 to 0x007F (US-ASCII) are encoded as a single octet having a zero (0) bit in its highest position: 0xxxxxxx.
- Characters in the range of 0x0080 to 0x07EF are encoded as two octets according to 110xxxxx 10xxxxxx, where x denote the bits of the given character to be inserted from the right
- Characters in the range of 0x0800 to 0xFFFF are encoded as three octets according to 1110xxxx 10xxxxxx 10xxxxxx, where x denote the bits of the given character to be inserted from the right
Characters out of range will raise a CodingException.
When creating a new UTF8String object the value to be represented has to be supplied as Java String type:
```
 String s = ...;
 UTF8String UTF8String = new UTF8String(s);
 
```
When calling the getValue method for getting the inherent string value from an ASN.1 UTF8String instance, a Java object of type String is returned:
```
 String s = (String)UTF8String.getValue();
 
```
DER en/decoding generally is done by means of the several methods of the DerCoder class; decoding alternatively may be performed by using the DerInputStream utility.
See Also:

ASN1Object, ASN

Field Summary
- Fields inherited from class iaik.asn1.ASN1String
  value
- Fields inherited from class iaik.asn1.ASN1Object
  asnType, constructed, encode_listener, indefinite_length, isStringType, stream_mode

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`UTF8String()` Creates an empty UTF8String.
	`UTF8String(java.lang.String value)` Creates a new ASN.1 UTF8String object for the given String value.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static java.lang.String`	`getRFC2253String(char[] str)` Returns a UTF-8 String representation according to RFC 2253.
`static java.lang.String`	`getRFC2253String(java.lang.String str)` Returns a UTF-8 String representation according to RFC 2253.
`static java.lang.String`	`getRFC2253String(java.lang.String input, boolean escapeNonPrintableAndNonAscii)` Returns a RFC 2253 representation of a string.
`static java.lang.String`	`getStringFromUTF8Encoding(byte[] enc)` Decodes the string from an UTF-8 encoded byte array.
`static byte[]`	`getUTF8EncodingFromCharArray(char[] str)` UTF-8 encodes the given char array.
`static byte[]`	`getUTF8EncodingFromString(java.lang.String str)` UTF-8 encodes the given string.
`java.lang.Object`	`getValue()` Returns the value of this UTF8String as a String object.
`void`	`setValue(java.lang.Object object)` Sets the value of this UTF8String.

Methods inherited from class iaik.asn1.ASN1String
decode, encode, equals, hashCode, toString

Methods inherited from class iaik.asn1.ASN1Object
addComponent, addEncodeListener, countComponents, encodeObject, getAsnType, getComponentAt, indefiniteLength, isA, isConstructed, isStringType, setAutomaticRepair, setAutomaticRepairRecursive, setIndefiniteLength, setIndefiniteRecursive

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - UTF8String
```
protected UTF8String()
```
    Creates an empty UTF8String.
  - UTF8String
```
public UTF8String(java.lang.String value)
```
    Creates a new ASN.1 UTF8String object for the given String value.
    
    Parameters:
    
    value - the String value this UTF8String object should be initialized with
- Method Detail
  - getValue
```
public java.lang.Object getValue()
```
    Returns the value of this UTF8String as a String object.
    
    Specified by:
    
    getValue in class ASN1Object
    
    Returns:
    
    the value of this UTF8String as a String object
  - setValue
```
public void setValue(java.lang.Object object)
```
    Sets the value of this UTF8String.
    The supplied value has to be a Java object of type String.
    
    Specified by:
    
    setValue in class ASN1Object
    
    Parameters:
    
    object - the Java String value to be set for this UTF8String
  - getUTF8EncodingFromString
```
public static byte[] getUTF8EncodingFromString(java.lang.String str)
                                        throws CodingException
```
    UTF-8 encodes the given string.
    
    Parameters:
    
    str - the string to be encoded
    
    Returns:
    
    the UTF-8 encoding as byte array
    
    Throws:
    
    CodingException - if an coding error occurs
  - getUTF8EncodingFromCharArray
```
public static byte[] getUTF8EncodingFromCharArray(char[] str)
                                           throws CodingException
```
    UTF-8 encodes the given char array.
    
    Parameters:
    
    str - the char array to be encoded
    
    Returns:
    
    the UTF-8 encoding as byte array
    
    Throws:
    
    CodingException - if an coding error occurs
  - getStringFromUTF8Encoding
```
public static java.lang.String getStringFromUTF8Encoding(byte[] enc)
                                                  throws CodingException
```
    Decodes the string from an UTF-8 encoded byte array. This method is static not private to provide access for the DerInputStream class.
    
    Parameters:
    
    enc - the UTF-8 encoding as byte array
    
    Returns:
    
    the decoded string
    
    Throws:
    
    CodingException - if an error occurs during the decoding process
  - getRFC2253String
```
public static java.lang.String getRFC2253String(java.lang.String str)
                                         throws CodingException
```
    Returns a UTF-8 String representation according to RFC 2253.
    RFC 2253 specifies a string representation of Distinguished Names as used for LDAP lookups.
    The string representation returned by this method is based on the algorithm given in section 2.4 of RFC 2253 thereby applying the following escaping mechanisms:
    - A space or "#" character at the beginning of the string is escaped.
    - A space at the end of the string is escaped.
    - Any of the characters ",", "+", """, "\", "<", ">" or ";" is escaped.
    - Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding. The space character (0x21) only is escaped when appearing at the beginning or the end of the string.
    Parameters:
    
    str - the string to be represented
    
    Returns:
    
    the string representation according to RFC 2253.
    
    Throws:
    
    CodingException - if an coding error occurs
  - getRFC2253String
```
public static java.lang.String getRFC2253String(char[] str)
                                         throws CodingException
```
    Returns a UTF-8 String representation according to RFC 2253.
    RFC 2253 specifies a string representation of Distinguished Names as used for LDAP lookups.
    The string representation returned by this method is based on the algorithm given in section 2.4 of RFC 2253 thereby applying the following escaping mechanisms:
    - A space or "#" character at the beginning of the string is escaped.
    - A space at the end of the string is escaped.
    - Any of the characters ",", "+", """, "\", "<", ">" or ";" is escaped.
    - Any non printable ASCII (< 0x21 or > 0x7e) and any non-ASCII character is escaped by an hexadecimal representation of its UTF-8 encoding. The space character (0x21) only is escaped when appearing at the beginning or the end of the string.
    Parameters:
    
    str - the char array to be represented
    
    Returns:
    
    the string representation according to RFC 2253.
    
    Throws:
    
    CodingException - if an coding error occurs
  - getRFC2253String
```
public static java.lang.String getRFC2253String(java.lang.String input,
                                                boolean escapeNonPrintableAndNonAscii)
```
    Returns a RFC 2253 representation of a string.
    
    Parameters:
    
    input - a string
    
    escapeNonPrintableAndNonAscii - indicates whether or not every non-printable character and non-ASCII character should be represented in escaped format
    
    Returns:
    
    the RFC 2253 representation of the string.
    
    Since:
    
    8.0 patch

Class UTF8String

Field Summary

Fields inherited from class iaik.asn1.ASN1String

Fields inherited from class iaik.asn1.ASN1Object

Constructor Summary

Method Summary

Methods inherited from class iaik.asn1.ASN1String

Methods inherited from class iaik.asn1.ASN1Object

Methods inherited from class java.lang.Object

Constructor Detail

UTF8String

UTF8String

Method Detail

getValue

setValue

getUTF8EncodingFromString

getUTF8EncodingFromCharArray

getStringFromUTF8Encoding

getRFC2253String

getRFC2253String

getRFC2253String