Programming Wireless Devices with the Java2 Platform

5.2 Classes Derived from Java 2 Standard Edition

CLDC provides a number of classes that have been derived from Java 2 Standard Edition (J2SE). The rules for J2ME configurations require that each class with the same name and package name as a J2SE class must be identical to or a subset of the corresponding J2SE class. The semantics of the classes and their methods included in the subset may not be changed. The classes may not add any public or protected methods or fields that are not available in the corresponding J2SE classes.

5.2.1 System Classes

J2SE class libraries include several classes that are intimately coupled with the Java Virtual Machine. Similarly, several commonly used Java tools assume the presence of certain classes in the system. For instance, the standard Java compiler (javac) generates code that requires certain methods of classes String and StringBuffer to be available.

The system classes included in the CLDC Specification are listed below. Each of these classes is a subset of the corresponding class in J2SE. Note that in CLDC 1.1, many of these classes contain additional methods that are not present in CLDC 1.0. Refer to CLDC library documentation in the end of this book for more details on each class, as well as for the differences between CLDC 1.0 and 1.1.

java.lang.Object
java.lang.Class
java.lang.Runtime
java.lang.System
java.lang.Thread
java.lang.Runnable (interface)
java.lang.String
java.lang.StringBuffer
java.lang.Throwable

5.2.2 Data Type Classes

The following basic data type classes from package java.lang are supported. Each of these classes is a subset of the corresponding class in J2SE. Classes Float and Double are new in CLDC 1.1.

java.lang.Boolean
java.lang.Byte
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double
java.lang.Character

5.2.3 Collection Classes

The following collection classes from package java.util are supported.

java.util.Vector
java.util.Stack
java.util.Hashtable
java.util.Enumeration (interface)

5.2.4 Input/Output Classes

The following classes from package java.io are supported.

java.io.InputStream
java.io.OutputStream
java.io.ByteArrayInputStream
java.io.ByteArrayOutputStream
java.io.DataInput (interface)
java.io.DataOutput (interface)
java.io.DataInputStream
java.io.DataOutputStream
java.io.Reader
java.io.Writer
java.io.InputStreamReader
java.io.OutputStreamWriter
java.io.PrintStream

5.2.5 Calendar and Time Classes

CLDC includes a small subset of the standard J2SE classes java.util.Calendar, java.util.Date, and java.util.TimeZone. To conserve space, the CLDC Specification requires only one time zone to be supported. By default, this time zone is GMT. Additional time zones may be provided by manufacturer-specific implementations of CLDC as long as the time zones are compatible with those provided by Java 2 Standard Edition.

java.util.Calendar
java.util.Date
java.util.TimeZone

5.2.6 Additional Classes

Two additional utility classes are provided. Class java.util.Random provides a simple pseudo-random number generator that is useful for implementing applications such as games. Class java.lang.Math provides methods min, max, and abs, which are frequently used by other Java library classes. In CLDC 1.1, class java.lang.Math also includes support for floating point trigonometric functions and square root calculation, as well as some additional utility functions such as ceil and floor.

java.util.Random
java.lang.Math

5.2.7 Exception and Error Classes

Since the libraries included in CLDC are generally intended to be compatible with J2SE libraries, the library classes included in CLDC throw precisely the same exceptions as regular J2SE classes do. Consequently, a fairly comprehensive set of exception classes has been included.

In contrast, as explained in Section 4.3.2, "Error-Handling Limitations," the error-handling capabilities of CLDC are limited. By default, a virtual machine conforming to CLDC is required to provide only the error classes listed below. (Class NoClassDefFoundError was added to the libraries in CLDC 1.1.)

Error classes

java.lang.Error
java.lang.NoClassDefFoundError
java.lang.OutOfMemoryError
java.lang.VirtualMachineError

Exception classes

java.lang.Exception
java.lang.ArithmeticException
java.lang.ArrayIndexOutOfBoundsException
java.lang.ArrayStoreException
java.lang.ClassCastException
java.lang.ClassNotFoundException
java.lang.IllegalAccessException
java.lang.IllegalArgumentException
java.lang.IllegalMonitorStateException
java.lang.IllegalThreadStateException
java.lang.IndexOutOfBoundsException
java.lang.InstantiationException
java.lang.InterruptedException
java.lang.NegativeArraySizeException
java.lang.NullPointerException
java.lang.RuntimeException
java.lang.NumberFormatException
java.lang.SecurityException
java.lang.StringIndexOutOfBoundsException

java.util.EmptyStackException
java.util.NoSuchElementException

java.io.EOFException
java.io.InterruptedIOException
java.io.IOException
java.io.UnsupportedEncodingException
java.io.UTFDataFormatException

5.2.8 Weak References

As of CLDC Specification version 1.1, the following classes are supported:

java.lang.ref.Reference
java.lang.ref.WeakReference

5.2.9 Internationalization Support

Character sets and character case conversion support

A CLDC implementation is required to support Unicode characters. Character information is based on the Unicode Standard, version 3.0. However, since the full character case conversion tables required for Unicode support are excessively large for devices with tight memory budgets, by default the case conversion facilities in CLDC assume the presence of ISO Latin-1 range of characters only. More specifically, implementations must provide support for character properties and case conversions for characters in the "Basic Latin" and "Latin-1 Supplement" blocks of Unicode 3.0. Other Unicode character blocks may be supported as necessary.

Character encodings

CLDC includes limited support for the translation of Unicode characters to and from a sequence of bytes. In J2SE this is done using objects called Readers and Writers, and this same mechanism is utilized in CLDC using the InputStreamReader and OutputStreamWriter classes with identical constructors.

new InputStreamReader(InputStream is);
new InputStreamReader(InputStream is, String enc)
    throws UnsupportedEncodingException;
new OutputStreamWriter(OutputStream os);
new OutputStreamWriter(OutputStream os, String enc)
    throws UnsupportedEncodingException;

If the enc parameter is present, it is the name of the encoding to be used. Where it is not, a default encoding (defined by the system property microedition.encoding) is used. Additional converters may be provided by manufacturer-specific implementations of CLDC. If a converter for a certain encoding is not available, an UnsupportedEncodingException is thrown.

For official information on character encodings in J2SE, refer to: http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html.

No localization support

Note that CLDC does not provide any localization features. All the solutions related to the formatting of dates, times, currencies and so on are assumed to be outside the scope of the CLDC Specification.

5.2.10 Property Support

CLDC libraries do not include the java.util.Properties class familiar from Java 2 Standard Edition. In J2SE, that class is used for storing system properties such as the name of the host operating system, version number of the virtual machine and so on.

In CLDC, a limited set of system properties described in Table 5.1 is available. These properties can be accessed by calling the method System.getProperty(String key).

Table 5.1. Standard system properties

Key	Explanation	Value
microedition.platform	Name of the host platform or device	(implementation-dependent)
microedition.encoding	Default character encoding	"ISO-8859-1"
microedition.configuration	Name and version of the supported configuration	"CLDC-1.1"
microedition.profiles	Names of the supported profiles	(implementation-dependent)

Property microedition.encoding describes the default character encoding name. This information is used by the system to find the correct class for the default character encoding for supporting internationalization. Property microedition.platform characterizes the host platform or device. Property microedition.configuration describes the current J2ME configuration and version, and property microedition.profiles defines a string containing the names of the supported profiles, separated by blanks.

Note that the set of properties defined above can be extended by J2ME profile specifications or device manufacturers. For instance, the MIDP Specification defines additional properties not included in Table 5.1. The set of system properties defined by the Mobile Information Device Profile can be found in Section 20.2, "System Properties."

Manufacturer-specific property definitions are prefixed with the same package name that the manufacturer-specific classes use (such as "com.companyname.propertyname"). The "microedition" namespace, as well as the "java" and "javax" namespaces, are reserved and may only be extended by official J2ME configurations, profiles, or optional packages.