The input byte sequence is provided in a byte buffer or a series of such buffers. The output character sequence is written to a character buffer or a series of such buffers. A decoder should always be used by making the following sequence of method invocations, hereinafter referred to as a decoding operation:
Reset the decoder via the reset method, unless it has not been used before;
Invoke the decode method zero or more times, as long as additional input may be available, passing false for the endOfInput argument and filling the input buffer and flushing the output buffer between invocations;
Invoke the decode method one final time, passing true for the endOfInput argument; and then
Invoke the flush method so that the decoder can flush any internal state to the output buffer.
There are two general types of decoding errors. If the input byte
sequence is not legal for this charset then the input is considered malformed. If
the input byte sequence is legal but cannot be mapped to a valid
Unicode character then an unmappable character has been encountered.
How a decoding error is handled depends upon the action requested for
that type of error, which is described by an instance of the CodingErrorAction
class. The possible error actions are to ignore The default action for malformed-input and unmappable-character errors
is to report This class is designed to handle many of the details of the decoding
process, including the implementation of error actions. A decoder for a
specific charset, which is a concrete subclass of this class, need only
implement the abstract decodeLoop
method, which
encapsulates the basic decoding loop. A subclass that maintains internal
state should, additionally, override the flush
and reset
methods.
Instances of this class are not safe for use by multiple concurrent
threads.
the erroneous input, report
the error to the invoker via
the returned CoderResult
object, or replace
the erroneous input with the current value of the
replacement string. The replacement
has the initial value "\uFFFD";
its value may be changed via the replaceWith
method.
them. The
malformed-input error action may be changed via the onMalformedInput
method; the
unmappable-character action may be changed via the onUnmappableCharacter
method.
This method implements an entire decoding operation; that is, it resets this decoder, then it decodes the bytes in the given byte buffer, and finally it flushes this decoder. This method should therefore not be invoked if a decoding operation is already in progress.
The buffers are read from, and written to, starting at their current positions. At most bytes will be read and at most characters will be written. The buffers' positions will be advanced to reflect the bytes read and the characters written, but their marks and limits will not be modified.
In addition to reading bytes from the input buffer and writing characters to the output buffer, this method returns a CoderResult object to describe its reason for termination:
CoderResult#UNDERFLOW indicates that as much of the input buffer as possible has been decoded. If there are no bytes remaining and the invoker has no further input then the decoding operation is complete. Otherwise there is insufficient input for the operation to proceed, so this method should be invoked again with further input.
CoderResult#OVERFLOW indicates that the output buffer is full. This method should be invoked again with a non-full output buffer.
A malformed-input
result indicates that a malformed-input
error has been detected. The malformed bytes begin at the input
buffer's (possibly incremented) position; the number of malformed
bytes may be determined by invoking the result object's length
method. This case applies only if the
malformed action
of this decoder
is CodingErrorAction#REPORT
; otherwise the malformed input
will be ignored or replaced, as requested.
An unmappable-character
result indicates that an
unmappable-character error has been detected. The bytes that
decode the unmappable character begin at the input buffer's (possibly
incremented) position; the number of such bytes may be determined
by invoking the result object's length
method. This case applies only if the unmappable action
of this decoder is CodingErrorAction#REPORT
; otherwise the unmappable character will be
ignored or replaced, as requested.
The endOfInput parameter advises this method as to whether the invoker can provide further input beyond that contained in the given input buffer. If there is a possibility of providing additional input then the invoker should pass false for this parameter; if there is no possibility of providing further input then the invoker should pass true. It is not erroneous, and in fact it is quite common, to pass false in one invocation and later discover that no further input was actually available. It is critical, however, that the final invocation of this method in a sequence of invocations always pass true so that any remaining undecoded input will be treated as being malformed.
This method works by invoking the decodeLoop method, interpreting its results, handling error conditions, and reinvoking it as necessary.
If this decoder implements an auto-detecting charset then this method returns the actual charset once it has been detected. After that point, this method returns the same value for the duration of the current decoding operation. If not enough input bytes have yet been read to determine the actual charset then this method throws an IllegalStateException .
The default implementation of this method always throws an UnsupportedOperationException ; it should be overridden by auto-detecting decoders to return the appropriate value.
The equals method implements an equivalence relation
on non-null object references:
x, x.equals(x) should return
true.
x and y, x.equals(y)
should return true if and only if
y.equals(x) returns true.
x, y, and z, if
x.equals(y) returns true and
y.equals(z) returns true, then
x.equals(z) should return true.
x and y, multiple invocations of
x.equals(y) consistently return true
or consistently return false, provided no
information used in equals comparisons on the
objects is modified.
x,
x.equals(null) should return false.
The equals method for class Object implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x and
y, this method returns true if and only
if x and y refer to the same object
(x == y has the value true).
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
Some decoders maintain internal state and may need to write some final characters to the output buffer once the overall input sequence has been read.
Any additional output is written to the output buffer beginning at its current position. At most characters will be written. The buffer's position will be advanced appropriately, but its mark and limit will not be modified.
If this method completes successfully then it returns CoderResult#UNDERFLOW . If there is insufficient room in the output buffer then it returns CoderResult#OVERFLOW . If this happens then this method must be invoked again, with an output buffer that has more room, in order to complete the current decoding operation.
This method invokes the implFlush method to perform the actual flushing operation.
java.util.Hashtable.
The general contract of hashCode is:
hashCode method on each of
the two objects must produce the same integer result.
As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
The default implementation of this method always returns false; it should be overridden by auto-detecting decoders to return true.
If this decoder implements an auto-detecting charset then at a single point during a decoding operation this method may start returning true to indicate that a specific charset has been detected in the input byte sequence. Once this occurs, the detectedCharset method may be invoked to retrieve the detected charset.
That this method returns false does not imply that no bytes have yet been decoded. Some auto-detecting decoders are capable of decoding some, or even all, of an input byte sequence without fixing on a particular charset.
The default implementation of this method always throws an UnsupportedOperationException ; it should be overridden by auto-detecting decoders to return true once the input charset has been determined.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method invokes the implOnMalformedInput method, passing the new action.
This method invokes the implOnUnmappableCharacter method, passing the new action.
This method invokes the implReplaceWith method, passing the new replacement, after checking that the new replacement is acceptable.
This method resets charset-independent state and also invokes the implReset method in order to perform any charset-specific reset actions.
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.