Editing Java Platform, Standard Edition (section)

== General purpose packages ==
The majority of these packages are exported by the <code>java.base</code> module of the [[Java Platform Module System]] (since Java 9).

=== java.lang ===
The [[Java package]] {{Javadoc:SE|package=java.lang|java/lang|This shared link has expired.=This shared link has expired.}} contains fundamental classes and [[interface (Java)|interfaces]] closely tied to the language and [[Run time system|runtime]] system. This includes the root classes that form the [[class hierarchy]], types tied to the language definition, basic [[exception handling|exceptions]], math functions, [[thread (computer science)|threading]], security functions, as well as some information on the underlying native system. This package contains 22 of 32 <code>Error</code> classes provided in JDK 6.

The main classes and interfaces in <code>java.lang</code> are:

* {{Javadoc:SE|java/lang|Object}} – the class that is the root of every class hierarchy.
* {{Javadoc:SE|java/lang|Enum}} – the base class for [[enumerated type|enumeration classes]] (as of J2SE 5.0).
* {{Javadoc:SE|java/lang|Class}} – the class that is the root of the Java [[Reflection (computer science)|reflection]] system.
* {{Javadoc:SE|java/lang|Throwable}} – the class that is the base class of the exception class hierarchy.
* {{Javadoc:SE|java/lang|Error}}, {{Javadoc:SE|java/lang|Exception}}, and {{Javadoc:SE|java/lang|RuntimeException}} – the base classes for each exception type.
* {{Javadoc:SE|java/lang|Thread}} – the class that allows operations on threads.
* {{Javadoc:SE|java/lang|String}} – the class for [[string (computer science)|strings]] and [[string literal]]s.
* {{Javadoc:SE|java/lang|StringBuffer}} and {{Javadoc:SE|java/lang|StringBuilder}} – classes for performing [[StringBuffer and StringBuilder|string manipulation]] (<code>StringBuilder</code> as of J2SE 5.0).
* {{Javadoc:SE|java/lang|Comparable}} – the interface that allows generic comparison and ordering of objects (as of J2SE 1.2).
* {{Javadoc:SE|java/lang|Iterable}} – the interface that allows generic iteration using the [[Foreach#Java|enhanced <code>for</code> loop]] (as of J2SE 5.0).
* {{Javadoc:SE|java/lang|ClassLoader}}, {{Javadoc:SE|java/lang|Process}}, {{Javadoc:SE|java/lang|Runtime}}, {{Javadoc:SE|java/lang|SecurityManager}}, and {{Javadoc:SE|java/lang|System}} – classes that provide "system operations" that manage the [[dynamically loaded library|dynamic loading]] of classes, creation of external [[process (computing)|processes]], host environment inquiries such as the time of day, and enforcement of [[security policy|security policies]].
* {{Javadoc:SE|java/lang|Math}} and {{Javadoc:SE|java/lang|StrictMath}} – classes that provide basic math functions such as [[sine]], [[cosine]], and [[square root]] (<code>StrictMath</code> as of J2SE 1.3).
* The [[primitive wrapper class]]es that [[encapsulation (computer science)|encapsulate]] [[primitive type]]s as [[object (computer science)|objects]].
* The basic exception classes thrown for language-level and other common exceptions.

Classes in <code>java.lang</code> are automatically imported into every [[source file]].

==== java.lang.ref ====
The {{Javadoc:SE|package=java.lang.ref|java/lang/ref}} package provides more flexible types of [[Reference (computer science)|references]] than are otherwise available, permitting limited interaction between the application and the [[Java virtual machine|Java Virtual Machine]] (JVM) [[garbage collection (computer science)|garbage collector]].  It is an important package, central enough to the language for the language designers to give it a name that starts with "java.lang", but it is somewhat special-purpose and not used by a lot of developers.  This package was added in J2SE 1.2.

Java has an expressive system of references and allows for special behavior for garbage collection. A normal reference in Java is known as a "strong reference". The <code>java.lang.ref</code> package defines three other types of references—soft, [[weak reference|weak]], and phantom references. Each type of reference is designed for a specific use.

* A {{Javadoc:SE|java/lang/ref|SoftReference}} can be used to implement a [[cache (computing)|cache]].  An object that is not reachable by a strong reference (that is, not strongly reachable), but is referenced by a soft reference is called "softly reachable". A softly reachable object may be garbage collected at the discretion of the garbage collector. This generally means that softly reachable objects are only garbage collected when free memory is low—but again, this is at the garbage collector's discretion. Semantically, a soft reference means, "Keep this object when nothing else references it, unless the memory is needed."
* A {{Javadoc:SE|java/lang/ref|WeakReference}} is used to implement weak maps.  An object that is not strongly or softly reachable, but is referenced by a weak reference is called "[[weakly reachable]]".  A weakly reachable object is garbage collected in the next collection cycle. This behavior is used in the class {{Javadoc:SE|package=java.util|java/util|WeakHashMap}}.  A weak map allows the programmer to put key/value pairs in the map and not worry about the objects taking up memory when the key is no longer reachable anywhere else.  Another possible application of weak references is the [[string intern pool]].  Semantically, a weak reference means "get rid of this object when nothing else references it at the next garbage collection."
* A {{Javadoc:SE|java/lang/ref|PhantomReference}} is used to reference objects that have been marked for garbage collection and have been [[finalizer|finalized]], but have not yet been reclaimed. An object that is not strongly, softly or weakly reachable, but is referenced by a phantom reference is called "phantom reachable." This allows for more flexible cleanup than is possible with the finalization mechanism alone.  Semantically, a phantom reference means "this object is no longer needed and has been finalized in preparation for being collected."

Each of these reference types extends the {{Javadoc:SE|java/lang/ref|Reference}} class, which provides the {{Javadoc:SE|name=get()|java/lang/ref|Reference|get()}} [[method (computer science)|method]] to return a strong reference to the referent object (or <code>null</code> if the reference has been cleared or if the reference type is phantom), and the {{Javadoc:SE|name=clear()|java/lang/ref|Reference|clear()}} method to clear the reference.

The <code>java.lang.ref</code> also defines the class {{Javadoc:SE|java/lang/ref|ReferenceQueue}}, which can be used in each of the applications discussed above to keep track of objects that have changed reference type.  When a <code>Reference</code> is created it is optionally registered with a reference queue.  The application polls the reference queue to get references that have changed reachability state.

==== java.lang.reflect ====
[[Reflection (computer science)|Reflection]] is a constituent of the [[Java (programming language)|Java]] API that lets Java code examine and "reflect" on Java components at runtime and use the reflected members. Classes in the {{Javadoc:SE|package=java.lang.reflect|java/lang/reflect}} package, along with <code>java.lang.Class</code> and {{Javadoc:SE|package=java.lang|java/lang|Package}} accommodate applications such as [[debugger]]s, [[interpreter (computing)|interpreters]], object inspectors, [[class browser]]s, and services such as object [[serialization]] and [[JavaBeans]] that need access to either the public members of a target object (based on its runtime class) or the members declared by a given class. This package was added in JDK 1.1.

Reflection is used to instantiate classes and invoke methods using their names, a concept that allows for dynamic programming.  Classes, interfaces, methods, [[field (computer science)|fields]], and [[constructor (computer science)|constructor]]s can all be discovered and used at runtime.  Reflection is supported by [[metadata]] that the JVM has about the program.

===== Techniques =====
There are basic techniques involved in reflection:

* Discovery – this involves taking an object or class and discovering the members, superclasses, implemented interfaces, and then possibly using the discovered elements.
* Use by name – involves starting with the symbolic name of an element and using the named element.

====== Discovery ======
Discovery typically starts with an object and calling the {{Javadoc:SE|java/lang|Object|getClass()}} method to get the object's <code>Class</code>.  The <code>Class</code> object has several methods for discovering the contents of the class, for example:

* {{Javadoc:SE|name=getMethods()|java/lang|Class|getMethods()}} – returns an array of {{Javadoc:SE|java/lang/reflect|Method}} objects representing all the public methods of the class or interface
* {{Javadoc:SE|name=getConstructors()|java/lang|Class|getConstructors()}} – returns an array of {{Javadoc:SE|java/lang/reflect|Constructor}} objects representing all the public constructors of the class
* {{Javadoc:SE|name=getFields()|java/lang|Class|getFields()}} – returns an array of {{Javadoc:SE|java/lang/reflect|Field}} objects representing all the public fields of the class or interface
* {{Javadoc:SE|name=getClasses()|java/lang|Class|getClasses()}} – returns an array of <code>Class</code> objects representing all the public classes and interfaces that are members (e.g. [[inner class]]es) of the class or interface
* {{Javadoc:SE|name=getSuperclass()|java/lang|Class|getSuperclass()}} – returns the <code>Class</code> object representing the superclass of the class or interface (<code>null</code> is returned for interfaces)
* {{Javadoc:SE|name=getInterfaces()|java/lang|Class|getInterfaces()}} – returns an array of <code>Class</code> objects representing all the interfaces that are implemented by the class or interface

====== Use by name ======
The <code>Class</code> object can be obtained either through discovery, by using the ''class literal'' (e.g. <code>MyClass.class</code>) or by using the name of the class (e.g. {{Javadoc:SE|name=Class.forName("mypackage.MyClass")|java/lang|Class|forName(java.lang.String)}}).  With a <code>Class</code> object, member <code>Method</code>, <code>Constructor</code>, or <code>Field</code> objects can be obtained using the symbolic name of the member.  For example:
* {{Javadoc:SE|name=getMethod("methodName", Class...)|java/lang|Class|getMethod(java.lang.String,java.lang.Class...)}} – returns the <code>Method</code> object representing the public method with the name "methodName" of the class or interface that accepts the parameters specified by the <code>Class...</code> parameters.
* {{Javadoc:SE|name=getConstructor(Class...)|java/lang|Class|getConstructor(java.lang.Class...)}} – returns the <code>Constructor</code> object representing the public constructor of the class that accepts the parameters specified by the <code>Class...</code> parameters.
* {{Javadoc:SE|name=getField("fieldName")|java/lang|Class|getField(java.lang.String)}} – returns the <code>Field</code> object representing the public field with the name "fieldName" of the class or interface.

<code>Method</code>, <code>Constructor</code>, and <code>Field</code> objects can be used to dynamically access the represented member of the class.  For example:
* {{Javadoc:SE|name=Field.get(Object)|java/lang/reflect|Field|get(java.lang.Object)}} – returns an <code>Object</code> containing the value of the field from the instance of the object passed to <code>get()</code>.  (If the <code>Field</code> object represents a static field then the <code>Object</code> parameter is ignored and may be <code>null</code>.)
* {{Javadoc:SE|name=Method.invoke(Object, Object...)|java/lang/reflect|Method|invoke(java.lang.Object,java.lang.Object...)}} – returns an <code>Object</code> containing the result of invoking the method for the instance of the first <code>Object</code> parameter passed to <code>invoke()</code>.  The remaining <code>Object...</code> parameters are passed to the method.  (If the <code>Method</code> object represents a [[static method]] then the first <code>Object</code> parameter is ignored and may be <code>null</code>.)
* {{Javadoc:SE|name=Constructor.newInstance(Object...)|java/lang/reflect|Constructor|newInstance(java.lang.Object...)}} – returns the new <code>Object</code> instance from invoking the constructor.  The <code>Object...</code> parameters are passed to the constructor. (Note that the parameterless constructor for a class can also be invoked by calling {{Javadoc:SE|name=newInstance()|java/lang|Class|newInstance()}}.)

===== Arrays and proxies =====
The <code>java.lang.reflect</code> package also provides an {{Javadoc:SE|java/lang/reflect|Array}} class that contains static methods for creating and manipulating array objects, and since J2SE 1.3, a {{Javadoc:SE|java/lang/reflect|Proxy}} class that supports dynamic creation of proxy classes that implement specified interfaces.

The implementation of a <code>Proxy</code> class is provided by a supplied object that implements the {{Javadoc:SE|java/lang/reflect|InvocationHandler}} interface.  The <code>InvocationHandler</code>'s {{Javadoc:SE|name=invoke(Object, Method, Object&#91;&#93;)|java/lang/reflect|InvocationHandler|invoke(java.lang.Object,java.lang.reflect.Method,java.lang.Object&#91;&#93;)}} method is called for each method invoked on the proxy object—the first parameter is the proxy object, the second parameter is the <code>Method</code> object representing the method from the interface implemented by the proxy, and the third parameter is the array of parameters passed to the interface method.  The <code>invoke()</code> method returns an <code>Object</code> result that contains the result returned to the code that called the proxy interface method.

=== java.io ===
The {{Javadoc:SE|package=java.io|java/io}} package contains classes that support [[input/output|input and output]].  The classes in the package are primarily [[stream (computing)|stream-oriented]]; however, a class for [[random access]] [[Computer file|files]] is also provided. The central classes in the package are {{Javadoc:SE|java/io|InputStream}} and {{Javadoc:SE|java/io|OutputStream}}, which are [[Class (computer science)#Concrete classes|abstract]] base classes for reading from and writing to [[byte stream]]s, respectively.  The related classes {{Javadoc:SE|java/io|Reader}} and {{Javadoc:SE|java/io|Writer}} are abstract base classes for reading from and writing to [[character (computing)|character]] streams, respectively.  The package also has a few miscellaneous classes to support interactions with the host [[file system]].

==== Streams ====
The stream classes follow the [[decorator pattern]] by extending the base subclass to add features to the stream classes. Subclasses of the base stream classes are typically named for one of the following attributes:

* the source/destination of the stream data
* the type of data written to/read from the stream
* additional processing or filtering performed on the stream data

The stream subclasses are named using the naming [[pattern]] <code>''XxxStreamType''</code> where <code>''Xxx''</code> is the name describing the feature and <code>''StreamType''</code> is one of <code>InputStream</code>, <code>OutputStream</code>, <code>Reader</code>, or <code>Writer</code>.

The following table shows the sources/destinations supported directly by the <code>java.io</code> package:

{| class="wikitable"
|-
! Source/Destination !! Name !! Stream types !! In/out !! Classes
|-
| <code>[[byte]]</code> [[Array (data type)|array]] (<code>byte[]</code>) || <code>ByteArray</code> || <code>byte</code> || in, out
| {{Javadoc:SE|java/io|ByteArrayInputStream}}, {{Javadoc:SE|java/io|ByteArrayOutputStream}}
|-
| <code>char</code> array (<code>char[]</code>) || <code>CharArray</code> || <code>char</code> || in, out
| {{Javadoc:SE|java/io|CharArrayReader}}, {{Javadoc:SE|java/io|CharArrayWriter}}
|-
| [[Computer file|file]] || <code>File</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|FileInputStream}}, {{Javadoc:SE|java/io|FileOutputStream}}, {{Javadoc:SE|java/io|FileReader}}, {{Javadoc:SE|java/io|FileWriter}}
|-
| [[string (computer science)|string]] (<code>[[StringBuffer and StringBuilder|StringBuffer]]</code>) || <code>String</code> || <code>char</code> || in, out
| {{Javadoc:SE|java/io|StringReader}}, {{Javadoc:SE|java/io|StringWriter}}
|-
| [[thread (computing)|thread]] (<code>Thread</code>) || <code>Piped</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|PipedInputStream}}, {{Javadoc:SE|java/io|PipedOutputStream}}, {{Javadoc:SE|java/io|PipedReader}}, {{Javadoc:SE|java/io|PipedWriter}}
|}

Other standard library packages provide stream implementations for other destinations, such as the <code>InputStream</code> returned by the {{Javadoc:SE|package=java.net|java/net|Socket|getInputStream()}} method or the Java EE {{Javadoc:EE|package=javax.servlet|javax/servlet|ServletOutputStream}} class.

Data type handling and processing or filtering of stream data is accomplished through stream [[filter (software)|filters]].  The filter classes all accept another compatible stream object as a parameter to the constructor and ''decorate'' the enclosed stream with additional features.  Filters are created by extending one of the base filter classes {{Javadoc:SE|java/io|FilterInputStream}}, {{Javadoc:SE|java/io|FilterOutputStream}}, {{Javadoc:SE|java/io|FilterReader}}, or {{Javadoc:SE|java/io|FilterWriter}}.

The <code>Reader</code> and <code>Writer</code> classes are really just byte streams with additional processing performed on the data stream to convert the bytes to characters.  They use the default [[character encoding]] for the platform, which as of J2SE 5.0 is represented by the {{Javadoc:SE|java/nio/charset|Charset}} returned by the {{Javadoc:SE|package=java.nio.charset|java/nio/charset|Charset|defaultCharset()}} static method.  The {{Javadoc:SE|java/io|InputStreamReader}} class converts an <code>InputStream</code> to a <code>Reader</code> and the {{Javadoc:SE|java/io|OutputStreamWriter}} class converts an <code>OutputStream</code> to a <code>Writer</code>.  Both these classes have constructors that support specifying the character encoding to use. If no encoding is specified, the program uses the default encoding for the platform.

The following table shows the other processes and filters that the <code>java.io</code> package directly supports.  All these classes extend the corresponding <code>Filter</code> class.

{| class="wikitable"
|-
! Operation !! Name !! Stream types !! In/out !! Classes
|-
| [[buffer (computer science)|buffering]] || <code>Buffered</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|BufferedInputStream}}, {{Javadoc:SE|java/io|BufferedOutputStream}}, {{Javadoc:SE|java/io|BufferedReader}}, {{Javadoc:SE|java/io|BufferedWriter}}
|-
| "push back" last value read || <code>Pushback</code> || <code>byte</code>, <code>char</code> || in
| {{Javadoc:SE|java/io|PushbackInputStream}}, {{Javadoc:SE|java/io|PushbackReader}}
|-
| read/write [[primitive type]]s || <code>Data</code> || <code>byte</code> || in, out
| {{Javadoc:SE|java/io|DataInputStream}}, {{Javadoc:SE|java/io|DataOutputStream}}
|-
| [[object serialization]] (read/write objects) || <code>Object</code> || byte || in, out
| {{Javadoc:SE|java/io|ObjectInputStream}}, {{Javadoc:SE|java/io|ObjectOutputStream}}
|}

==== Random access ====
The {{Javadoc:SE|java/io|RandomAccessFile}} class supports ''[[random access]]'' reading and writing of files.  The class uses a ''[[Data file#File pointers and random access|file pointer]]'' that represents a byte-offset within the file for the next read or write operation.  The file pointer is moved implicitly by reading or writing and explicitly by calling the {{Javadoc:SE|name=seek(long)|java/io|RandomAccessFile|seek(long)}} or {{Javadoc:SE|name=skipBytes(int)|java/io|RandomAccessFile|skipBytes(int)}} methods.  The current position of the file pointer is returned by the {{Javadoc:SE|name=getFilePointer()|java/io|RandomAccessFile|getFilePointer()}} method.

==== File system ====
The {{Javadoc:SE|java/io|File}} class represents a [[Computer file|file]] or [[directory (file systems)|directory]] [[path (computing)|path]] in a [[file system]].  <code>File</code> objects support the creation, deletion and renaming of files and directories and the manipulation of [[file attribute]]s such as ''read-only'' and ''last modified timestamp''.  <code>File</code> objects that represent directories can be used to get a list of all the contained files and directories.

The {{Javadoc:SE|java/io|FileDescriptor}} class is a [[file descriptor]] that represents a source or sink (destination) of bytes.  Typically this is a file, but can also be a [[System console|console]] or [[network socket]].  <code>FileDescriptor</code> objects are used to create <code>File</code> streams.  They are obtained from <code>File</code> streams and <code>java.net</code> sockets and datagram sockets.

=== java.nio ===
{{Main|Non-blocking I/O (Java)}}

In J2SE 1.4, the package {{Javadoc:SE|package=java.nio|java/nio}} (NIO or Non-blocking I/O) was added to support [[memory-mapped I/O]], facilitating [[Input/output|I/O]] operations closer to the underlying hardware with sometimes dramatically better performance.  The <code>java.nio</code> package provides support for a number of buffer types.  The subpackage {{Javadoc:SE|package=java.nio.charset|java/nio/charset}} provides support for different [[character encoding]]s for character data.  The subpackage {{Javadoc:SE|package=java.nio.channels|java/nio/channels}} provides support for ''channels,'' which represent connections to entities that are capable of performing I/O operations, such as files and sockets.  The <code>java.nio.channels</code> package also provides support for fine-grained locking of files.

=== java.math ===
The {{Javadoc:SE|package=java.math|java/math}} package supports [[Arbitrary-precision arithmetic|multiprecision arithmetic]] (including modular arithmetic operations) and provides multiprecision prime number generators used for cryptographic key generation. The main classes of the package are:

* {{Javadoc:SE|java/math|BigDecimal}} – provides arbitrary-precision signed decimal numbers. <code>BigDecimal</code> gives the user control over rounding behavior through <code>RoundingMode</code>.
* {{Javadoc:SE|java/math|BigInteger}} – provides arbitrary-precision integers. Operations on <code>BigInteger</code> do not [[Arithmetic overflow|overflow]] or lose precision. In addition to standard arithmetic operations, it provides [[modular arithmetic]], [[Greatest common divisor|GCD]] calculation, [[primality testing]], [[prime number]] generation, [[bit]] manipulation, and other miscellaneous operations.
* {{Javadoc:SE|java/math|MathContext}}  – encapsulate the context settings that describe certain rules for numerical operators.
* {{Javadoc:SE|java/math|RoundingMode}} – an enumeration that provides eight rounding behaviors.

=== java.net ===
The {{Javadoc:SE|package=java.net|java/net}} package provides special IO routines for networks, allowing [[HTTP]] requests, as well as other common transactions.

=== java.text ===
The {{Javadoc:SE|package=java.text|java/text}} package implements parsing routines for strings and supports various human-readable languages and locale-specific parsing.

=== java.util ===
[[Data structure]]s that aggregate objects are the focus of the {{Javadoc:SE|package=java.util|java/util}} package. Included in the package is the [[Collections API]], an organized data structure hierarchy influenced heavily by the [[design pattern (computer science)|design patterns]] considerations.