+ +
+The applet framework involves two +entities: the applet and the applet context. An applet is an +embeddable window (see the Panel class) with a few extra methods that the applet +context can use to initialize, start, and stop the applet. +
+The applet context is an application that is responsible for loading and running +applets. For example, the applet context could be a Web browser or an applet +development environment. +
+ + +@since JDK1.0 + + diff --git a/out/production/classes1/awt/color/package.html b/out/production/classes1/awt/color/package.html new file mode 100644 index 0000000000000000000000000000000000000000..41fa95a2f8dce4d62a8f2feb49527d4e6e832d7d --- /dev/null +++ b/out/production/classes1/awt/color/package.html @@ -0,0 +1,55 @@ + + + + +
+It also provides a clipboard mechanism, which is an object that +temporarily holds a transferable object that can be transferred +between or within an application. The clipboard is typically used +for copy and paste operations. Although it is possible to create +a clipboard to use within an application, most applications will +use the system clipboard to ensure the data can be transferred +across applications running on the platform. + + + +@since JDK1.1 + + diff --git a/out/production/classes1/awt/dnd/package.html b/out/production/classes1/awt/dnd/package.html new file mode 100644 index 0000000000000000000000000000000000000000..467348506a52ad72d1be9f695c574289f95516b3 --- /dev/null +++ b/out/production/classes1/awt/dnd/package.html @@ -0,0 +1,146 @@ + + + + +
+This package defines the classes and interfaces necessary to perform Drag +and Drop operations in Java. It +defines classes for the drag-source and the drop-target, as well as +events for transferring the data being dragged. This package also provides +a means for giving visual feedback to the user throughout the +duration of the Drag and Drop operation. +
+A typical Drag and Drop operation can be decomposed into the following +states (not entirely sequentially): +
DragSource comes into existence,
+associated with some presentation
+element (Component) in the GUI, to initiate a Drag and Drop of
+some potentially Transferable data.
+DropTarget(s) come into/go out of
+existence, associated
+with presentation elements in the GUI (Components), potentially
+capable of consuming Transferable data types.
+DragGestureRecognizer is
+obtained from the DragSource and is
+associated with a Component in order
+to track and identify any Drag
+initiating gesture by the user over the Component.
+Component,
+which the registered
+DragGestureRecognizer detects, and notifies its
+DragGestureListener of.
+
+Note: Although this API consistently refers to the stimulus for a
+drag and drop operation being a physical gesture by a human user, this
+does not preclude a programmatically driven DnD operation given the
+appropriate implementation of a DragSource. This package
+contains the abstract class MouseDragGestureRecognizer for
+recognizing mouse device gestures. Other abstract subclasses may be
+provided by the platform to support other input devices or
+particular Component class semantics.
+
+
DragGestureListener causes the
+DragSource to initiate the Drag
+and Drop operation on behalf of the user, perhaps animating the
+GUI Cursor and/or rendering an Image of the item(s) that are the
+subject of the operation.
+Component(s)
+in the GUI with
+associated DropTarget(s), the DragSource
+receives notifications in order
+to provide "Drag Over" feedback effects, and the DropTarget(s)
+receive notifications in order to provide "Drag Under" feedback effects
+based upon the operation(s) supported and the data type(s) involved.
+
+
+The gesture itself moves a logical cursor across the GUI hierarchy,
+intersecting the geometry of GUI Component(s), possibly resulting in
+the logical "Drag" cursor entering, crossing, and subsequently
+leaving Component(s) and associated DropTarget(s).
+
+The DragSource object manifests "Drag Over" feedback to the user, in the typical case by animating the GUI Cursor associated with the
+logical cursor.
+
+DropTarget objects manifest "Drag Under" feedback to the user, in
+the typical case, by rendering animations into their associated GUI
+Component(s) under the GUI Cursor.
+
+The determination of the feedback effects, and the ultimate success +or failure of the data transfer, should one occur, is parameterized +as follows: +
DragSource and DropTarget: Copy, Move or Reference(link).
+DragSource and the set of data types comprehensible by the
+DropTarget.
+DragSource and DropTarget
+receive
+notifications that include, and result in the type negotiation and
+transfer of, the information associated with the DragSource via a
+Transferable object.
+main method of some class.
+The virtual machine terminates all its activity and exits when
+one of two things happens:
+exit method of class
+ Runtime or class System, and the exit
+ operation is permitted by the security manager.
+
+This implies that if an application doesn't start any threads itself,
+the JVM will exit as soon as main terminates.
+This is not the case, however, for a simple application
+that creates and displays a java.awt.Frame:
+
+ public static void main(String[] args) {
+ Frame frame = new Frame();
+ frame.setVisible(true);
+ }
+
+The reason is that AWT encapsulates asynchronous event dispatch
+machinery to process events AWT or Swing components can fire. The
+exact behavior of this machinery is implementation-dependent. In
+particular, it can start non-daemon helper threads for its internal
+purposes. In fact, these are the threads that prevent the example
+above from exiting. The only restrictions imposed on the behavior of
+this machinery are as follows:
+EventQueue.isDispatchThread
+ returns true if and only if the calling thread is the
+ event dispatch thread started by the machinery;
+ AWTEvents which were actually enqueued to a
+ particular EventQueue (note that events being
+ posted to the EventQueue can be coalesced) are
+ dispatched:
+ AWTEvent A is enqueued
+ to the EventQueue before
+ AWTEvent B then event B will not be
+ dispatched before event A.Component.isDisplayable).
+exit
+ method of class Runtime or class System
+ regardless of the presence of displayable components;
+ +Starting with 1.4, the behavior has changed as a result of the fix for + +4030718. With the current implementation, AWT terminates all its +helper threads allowing the application to exit cleanly when the +following three conditions are true: +
System.exit must:
+Window.dispose
+ on all top-level Windows. See
+Frame.getFrames.
+ EventQueue.
+ The argument is that methods
+ of AWT event listeners are typically executed on helper
+ threads.
+
+ <...>
+ Runnable r = new Runnable() {
+ public void run() {
+ Object o = new Object();
+ try {
+ synchronized (o) {
+ o.wait();
+ }
+ } catch (InterruptedException ie) {
+ }
+ }
+ };
+ Thread t = new Thread(r);
+ t.setDaemon(false);
+ t.start();
+ <...>
+
+
+The Java™ Virtual Machine Specification
+ guarantees
+that the JVM doesn't exit until this thread terminates.
+
+
diff --git a/out/production/classes1/awt/doc-files/BorderLayout-1.gif b/out/production/classes1/awt/doc-files/BorderLayout-1.gif
new file mode 100644
index 0000000000000000000000000000000000000000..8a1a2bb670f2c5443fc1e0f5a1fa505b5ef93927
Binary files /dev/null and b/out/production/classes1/awt/doc-files/BorderLayout-1.gif differ
diff --git a/out/production/classes1/awt/doc-files/Button-1.gif b/out/production/classes1/awt/doc-files/Button-1.gif
new file mode 100644
index 0000000000000000000000000000000000000000..1fd2f206f7f4dcd08260929f931d7365aa3c8299
Binary files /dev/null and b/out/production/classes1/awt/doc-files/Button-1.gif differ
diff --git a/out/production/classes1/awt/doc-files/Checkbox-1.gif b/out/production/classes1/awt/doc-files/Checkbox-1.gif
new file mode 100644
index 0000000000000000000000000000000000000000..c0bf0e2ba375fc0622fe7e1b435234242a987fbc
Binary files /dev/null and b/out/production/classes1/awt/doc-files/Checkbox-1.gif differ
diff --git a/out/production/classes1/awt/doc-files/CheckboxGroup-1.gif b/out/production/classes1/awt/doc-files/CheckboxGroup-1.gif
new file mode 100644
index 0000000000000000000000000000000000000000..a3a48a4d23c3c708ff1cc254f863fa0aa6b3e2a1
Binary files /dev/null and b/out/production/classes1/awt/doc-files/CheckboxGroup-1.gif differ
diff --git a/out/production/classes1/awt/doc-files/Choice-1.gif b/out/production/classes1/awt/doc-files/Choice-1.gif
new file mode 100644
index 0000000000000000000000000000000000000000..140c0f9cd04327677ff0590741d7b76e6b4fed45
Binary files /dev/null and b/out/production/classes1/awt/doc-files/Choice-1.gif differ
diff --git a/out/production/classes1/awt/doc-files/DesktopProperties.html b/out/production/classes1/awt/doc-files/DesktopProperties.html
new file mode 100644
index 0000000000000000000000000000000000000000..0153a07a97bd493eeb3f4f12886cdc6b8c85b983
--- /dev/null
+++ b/out/production/classes1/awt/doc-files/DesktopProperties.html
@@ -0,0 +1,277 @@
+
+
+
+
+
+Toolkit.getDesktopProperty method.
++Each desktop property is named by a unique string, which +is the "name" of that property. +
+Desktop properties supported by the AWT but not documented +elsewhere - typically because there is no suitable +method or class - are documented here. +
+Desktop properties documented elsewhere are those which are +tightly coupled with a method or class which documents them. +
+Since desktop properties abstract an underlying platform
+setting, they may not be available in environments that do
+not support them. In the event that a desktop property is
+unavailable for any reason, the implementation will return
+null.
+
+The following table summarizes the desktop properties documented
+here, and their value types.
+
+
| Property Name | +Value Type | +Summary Description | +
|---|---|---|
| awt.font.desktophints | +java.util.Map | +Font smoothing (text antialiasing) settings. | +
| sun.awt.enableExtraMouseButtons | +java.lang.Boolean | +Controls if mouse events from extra buttons are to be generated or not | +
+Modern desktops support various forms of text antialiasing (font smoothing). +
+These are applied by platform-specific heavyweight components.
+However an application may want to render text using the same text
+antialiasing on a drawing surface or lightweight (non-platform) component using
+ Graphics2D methods.
+This is particularly important when creating
+ Swing components which
+are required to appear consistent with native desktop components or other
+Swing components.
+
+
RenderingHints which
+can be directly applied to a Graphics2D.
+
+It is a Map as more than one hint may be needed.
+If non-null this can be directly applied to the Graphics2D.
+
+Toolkit tk = Toolkit.getDefaultToolkit();
+Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
+if (map != null) {
+ graphics2D.addRenderingHints(map);
+}
+
+An application can listen for changes in the property
+using a
+PropertyChangeListener :
+
+tk.addPropertyChangeListener("awt.font.desktophints", pcl);
++There is no direct way to discover if dynamic reconfiguration +is expected of running applications but the default assumption +should be that it is expected, since most modern desktop environments +do provide this capability. +
+Text always needs to be measured using the same
+ FontRenderContext
+as used for rendering. The text anti-aliasing hint is a component of
+the FontRenderContext.
+A FontMetrics
+obtained from the Graphics object on which the hint
+has been set will measure text appropriately.
+This is not a unique requirement for clients that specify this hint
+directly, since the value of the FontRenderContext should
+never be assumed, so is discussed here principally as a reminder.
+
+Sometimes an application may need to apply these hints on a shared +Graphics only temporarily, restoring the previous values after they +have been applied to text rendering operations. +The following sample code shows one way to do this. +
+/**
+ * Get rendering hints from a Graphics instance.
+ * "hintsToSave" is a Map of RenderingHint key-values.
+ * For each hint key present in that map, the value of that
+ * hint is obtained from the Graphics and stored as the value
+ * for the key in savedHints.
+ */
+RenderingHints getRenderingHints(Graphics2D g2d,
+ RenderingHints hintsToSave,
+ RenderingHints savedHints) {
+ if (savedHints == null) {
+ savedHints = new RenderingHints(null);
+ } else {
+ savedHints.clear();
+ }
+ if (hintsToSave.size() == 0) {
+ return savedHints;
+ }
+ /* RenderingHints.keySet() returns Set<Object> */
+ for (Object o : hintsToSave.keySet()) {
+ RenderingHints.Key key = (RenderingHints.Key)o;
+ Object value = g2d.getRenderingHint(key);
+ savedHints.put(key, value);
+ }
+ return savedHints;
+}
+
+
+Toolkit tk = Toolkit.getDefaultToolkit();
+Map map = (Map)(tk.getDesktopProperty("awt.font.desktophints"));
+Map oldHints;
+if (map != null) {
+ oldHints = getRenderingHints(graphic2D, map, null);
+ graphics2D.addRenderingHints(map);
+ ..
+ graphics2D.addRenderingHints(oldHints);
+}
+Map
+Map of
+RenderingHints such that every key is an instance of
+RenderingHints.Key and the value is a legal value for that key.
+Graphics2D. If the map did not contain
+the default value, then addRenderingHints(Map) would leave
+the previous hint which may not correspond to the desktop setting.
+
+An application can use setRenderingHints(Map) to reinitialise
+all hints, but this would affect unrelated hints too.
+
+
+"awt.font.desktophints" + "." + GraphicsDevice.getIDstring();
++An application can also listen for changes on these properties. +
+However this is an extremely unlikely configuration, so to help +ease of development, if only a single, desktop-wide setting is supported, +then querying each of these per-device settings will return null. +So to determine if there are per-device settings it is sufficient to +determine that there is a non-null return for any screen device using +the per-device property name. +
+This property determines if events from extra mouse buttons (if they are exist and are
+enabled by the underlying operating system) are allowed to be processed and posted into
+{@code EventQueue}.
+
+The value could be changed by passing "sun.awt.enableExtraMouseButtons"
+property value into java before application starts. This could be done with the following command:
+
+java -Dsun.awt.enableExtraMouseButtons=false Application ++Once set on application startup, it is impossible to change this value after. +
+ Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem + was inadequate. It suffered from major design and API problems, + as well as over a hundred open bugs. Many of these bugs were caused by + platform inconsistencies, or incompatibilities between the native + focus system for heavyweights and the Java focus system for + lightweights. +
+ The single worst problem with the AWT focus implementation was the + inability to query for the currently focused Component. Not only was + there no API for such a query, but also, because of an insufficient + architecture, such information was not even maintained by the code. +
+ Almost as bad was the inability of lightweight children of a Window
+ (not a Frame or a Dialog) to receive keyboard input. This problem
+ existed because Windows never received WINDOW_ACTIVATED
+ events and thus could never be activated, and only active Windows
+ could contain focused Components.
+
+ In addition, many developers noted that the APIs for FocusEvent and + WindowEvent were insufficient because they did not provide a way for + determining the "opposite" Component involved in the focus or + activation change. For example, when a Component received a FOCUS_LOST + event, it had no way of knowing which Component was gaining + focus. Since Microsoft Windows provides this functionality for free, + developers migrating from Microsoft Windows C/C++ or Visual Basic to + Java had been frustrated by the omission. +
+ To address these and other deficiencies, we have designed a new focus + model for the AWT in JDK 1.4. The primary design changes were the + construction of a new centralized KeyboardFocusManager class, and a + lightweight focus architecture. The amount of focus-related, + platform-dependent code has been minimized and replaced by fully + pluggable and extensible public APIs in the AWT. While we have + attempted to remain backward compatible with the existing + implementation, we were forced to make minor incompatible changes in + order to reach an elegant and workable conclusion. We anticipate that + these incompatibilities will have only a trivial impact on existing + applications. +
+ This document is a formal specification both of the new APIs and of + existing APIs which remain relevant in the new model. Combined with + the javadoc for focus-related classes and methods, this document + should enable developers to create substantial AWT and Swing + applications with a focus behavior that is customized yet consistent + across platforms. This document has the following sections: +
+ The focus model is centralized around a single class, + KeyboardFocusManager, that provides a set of APIs for client code to + inquire about the current focus state, initiate focus changes, and + replace default focus event dispatching with a custom dispatcher. + Clients can inquire about the focus state directly, or can register a + PropertyChangeListener that will receive PropertyChangeEvents when a + change to the focus state occurs. +
+ KeyboardFocusManager introduces the following main concepts and their + terminology: +
setFocusTraversalPolicyProvider on the Container.
+ + Every Window and JInternalFrame is, by default, a "focus cycle + root". If it's the only focus cycle root, then all of its + focusable descendants should be in its focus cycle, and its focus + traversal policy should enforce that they are by making sure that + all will be reached during normal forward (or backward) + traversal. If, on the other hand, the Window or JInternalFrame + has descendants that are also focus cycle roots, then each such + descendant is a member of two focus cycles: the one that it is + the root of, and the one of its nearest focus-cycle-root + ancestor. In order to traverse the focusable components belonging + to the focus cycle of such a "descendant" focus cycle root, one + first traverses (forward or backward) to reach the descendant, + and then uses the "down cycle" operation to reach, in turn, its + descendants. + +
+ Here is an example:
+
+
Assume the following: +
Window, which means that it
+ must be a focus cycle root.
+ Containers that
+ are focus cycle roots.
+ Container that is not a focus cycle root.
+ Components.
+ KeyboardFocusManager is an abstract class. AWT provides a default
+implementation in the DefaultKeyboardFocusManager class.
+
+
+
++Some browsers partition applets in different code bases into separate +contexts, and establish walls between these contexts. Each thread and +each Component is associated with a particular context and cannot +interfere with threads or access Components in other contexts. In such +a scenario, there will be one KeyboardFocusManager per context. Other +browsers place all applets into the same context, implying that there +will be only a single, global KeyboardFocusManager for all +applets. This behavior is implementation-dependent. Consult your +browser's documentation for more information. No matter how many +contexts there may be, however, there can never be more than one focus +owner, focused Window, or active Window, per ClassLoader. + + + +
+While the user's KeyEvents should generally be delivered to the focus +owner, there are rare cases where this is not desirable. An input +method is an example of a specialized Component that should receive +KeyEvents even though its associated text Component is and should +remain the focus owner. +
+A KeyEventDispatcher is a lightweight interface that allows client +code to pre-listen to all KeyEvents in a particular context. Instances +of classes that implement the interface and are registered with the +current KeyboardFocusManager will receive KeyEvents before they are +dispatched to the focus owner, allowing the KeyEventDispatcher to +retarget the event, consume it, dispatch it itself, or make other +changes. +
+For consistency, KeyboardFocusManager itself is a +KeyEventDispatcher. By default, the current KeyboardFocusManager will +be the sink for all KeyEvents not dispatched by the registered +KeyEventDispatchers. The current KeyboardFocusManager cannot be +completely deregistered as a KeyEventDispatcher. However, if a +KeyEventDispatcher reports that it dispatched the KeyEvent, regardless +of whether it actually did so, the KeyboardFocusManager will take no +further action with regard to the KeyEvent. (While it is possible for +client code to register the current KeyboardFocusManager as a +KeyEventDispatcher one or more times, there is no obvious reason why +this would be necessary, and therefore it is not recommended.) +
+Client-code may also post-listen to KeyEvents in a particular context +using the KeyEventPostProcessor interface. KeyEventPostProcessors +registered with the current KeyboardFocusManager will receive +KeyEvents after the KeyEvents have been dispatched to and handled by +the focus owner. The KeyEventPostProcessors will also receive +KeyEvents that would have been otherwise discarded because no +Component in the application currently owns the focus. This will allow +applications to implement features that require global KeyEvent post- +handling, such as menu shortcuts. +
+Like KeyEventDispatcher, KeyboardFocusManager also implements +KeyEventPostProcessor, and similar restrictions apply to its use in +that capacity. + + +
+The AWT defines the following six event types central to the focus
+model in two different java.awt.event classes:
+
WindowEvent.WINDOW_ACTIVATED: This event is
+ dispatched to a Frame or Dialog (but never a Window which
+ is not a Frame or Dialog) when it becomes the active Window.
+ WindowEvent.WINDOW_GAINED_FOCUS: This event is
+ dispatched to a Window when it becomes the focused Window.
+ Only focusable Windows can receive this event.
+ FocusEvent.FOCUS_GAINED: This event is dispatched
+ to a Component when it becomes the focus owner. Only focusable
+ Components can receive this event.
+ FocusEvent.FOCUS_LOST: This event is dispatched
+ to a Component when it is no longer the focus owner.
+ WindowEvent.WINDOW_LOST_FOCUS: This event is
+ dispatched to a Window when it is no longer the focused Window.
+ WindowEvent.WINDOW_DEACTIVATED: This event is
+ dispatched to a Frame or Dialog (but never a Window which is
+ not a Frame or Dialog) when it is no longer the active Window.
+ +If the focus is not in java application and the user clicks on a focusable +child Componenta of an inactive Frame b, the following events +will be dispatched and handled in order: + +
WINDOW_ACTIVATED event.
+ WINDOW_GAINED_FOCUS event.
+ FOCUS_GAINED event.
+ FOCUS_LOST event.
+ WINDOW_LOST_FOCUS event.
+ WINDOW_DEACTIVATED event.
+ WINDOW_ACTIVATED event.
+ WINDOW_GAINED_FOCUS event.
+ FOCUS_GAINED event.
+
+In addition, each event type will be dispatched in 1-to-1
+correspondence with its opposite event type. For example, if a
+Component receives a FOCUS_GAINED event, under no
+circumstances can it ever receive another FOCUS_GAINED
+event without an intervening FOCUS_LOST event.
+
+Finally, it is important to note that these events are delivered for
+informational purposes only. It is impossible, for example, to prevent
+the delivery of a pending FOCUS_GAINED event by requesting
+focus back to the Component losing focus while handling the preceding
+FOCUS_LOST event. While client code may make such a request,
+the pending FOCUS_GAINED will still be delivered,
+followed later by the events transferring focus back to the original
+focus owner.
+
+If it is absolutely necessary to suppress the FOCUS_GAINED event,
+client code can install a VetoableChangeListener which
+rejects the focus change. See Focus
+and VetoableChangeListener.
+
+
+
+
+Each event includes information about the "opposite" Component or
+Window involved in the focus or activation change. For example, for a
+FOCUS_GAINED event, the opposite Component is the Component
+that lost focus. If the focus or activation change occurs with a native
+application, with a Java application in a different VM or context, or
+with no other Component, then the opposite Component or Window is
+null. This information is accessible using
+FocusEvent.getOppositeComponent or
+WindowEvent.getOppositeWindow.
+
+On some platforms, it is not possible to discern the opposite +Component or Window when the focus or activation change occurs between +two different heavyweight Components. In these cases, the opposite +Component or Window may be set to null on some platforms, and to a +valid non-null value on other platforms. However, for a focus change +between two lightweight Components which share the same heavyweight +Container, the opposite Component will always be set correctly. Thus, +a pure Swing application can ignore this platform restriction when +using the opposite Component of a focus change that occurred within a +top-level Window. + + +
+FOCUS_GAINED and FOCUS_LOST events are
+marked as either temporary or permanent.
+
+Temporary FOCUS_LOST events are sent when a Component is
+losing the focus, but will regain the focus shortly. These events
+can be useful when focus changes are used as triggers for validation
+of data. For instance, a text Component may want to commit its
+contents when the user begins interacting with another Component,
+and can accomplish this by responding to FOCUS_LOST events.
+However, if the FocusEvent received is temporary,
+the commit should not be done, since the text field will be receiving
+the focus again shortly.
+
+A permanent focus transfer typically occurs as the result of a user
+clicking on a selectable, heavyweight Component, focus traversal with
+the keyboard or an equivalent input device, or from a call to
+requestFocus() or requestFocusInWindow().
+
+A temporary focus transfer typically occurs as the result of showing a +Menu or PopupMenu, clicking or dragging a Scrollbar, moving a Window +by dragging the title bar, or making another Window the focused +Window. Note that on some platforms, these actions may not generate +any FocusEvents at all. On others, temporary focus transfers will +occur. +
+When a Component receives a temporary FOCUS_LOST event,
+the event's opposite Component (if any) may receive a temporary
+FOCUS_GAINED event, but could also receive a permanent
+FOCUS_GAINED event. Showing a Menu or PopupMenu, or
+clicking or dragging a Scrollbar, should generate a temporary
+FOCUS_GAINED event. Changing the focused Window,
+however, will yield a permanent FOCUS_GAINED event
+for the new focus owner.
+
+The Component class includes variants of requestFocus and
+requestFocusInWindow which take a desired temporary state as a
+parameter. However, because specifying an arbitrary temporary state
+may not be implementable on all native windowing systems, correct
+behavior for this method can be guaranteed only for lightweight
+Components. This method is not intended for general use, but exists
+instead as a hook for lightweight Component libraries, such as Swing.
+
+
+
+Each Component defines its own Set of focus traversal keys for a given
+focus traversal operation. Components support separate Sets of keys
+for forward and backward traversal, and also for traversal up one
+focus traversal cycle. Containers which are focus cycle roots also
+support a Set of keys for traversal down one focus traversal cycle. If
+a Set is not explicitly defined for a Component, that Component
+recursively inherits a Set from its parent, and ultimately from a
+context-wide default set on the current KeyboardFocusManager.
+
+Using the AWTKeyStroke API, client code can specify
+on which of two specific KeyEvents, KEY_PRESSED or
+KEY_RELEASED, the focus traversal operation will occur.
+Regardless of which KeyEvent is specified, however, all KeyEvents
+related to the focus traversal key, including the associated
+KEY_TYPED event, will be consumed, and will not be
+dispatched to any Component. It is a runtime error to specify a
+KEY_TYPED event as mapping to a focus traversal operation,
+or to map the same event to multiple focus traversal operations for any
+particular Component or for a KeyboardFocusManager's defaults.
+
+The default focus traversal keys are implementation-dependent. Sun +recommends that the all implementations for a particular native +platform use the same keys. For Windows and Unix, the recommendations +are: + +
CTRL-TAB on KEY_PRESSED
+ TAB on KEY_PRESSED and
+ CTRL-TAB on KEY_PRESSED
+ CTRL-SHIFT-TAB on
+ KEY_PRESSED
+ SHIFT-TAB on KEY_PRESSED
+ and CTRL-SHIFT-TAB on
+ KEY_PRESSED
+
+Components can enable and disable all of their focus traversal keys en
+masse using Component.setFocusTraversalKeysEnabled. When focus
+traversal keys are disabled, the Component receives all KeyEvents for
+those keys. When focus traversal keys are enabled, the Component never
+receives KeyEvents for traversal keys; instead, the KeyEvents are
+automatically mapped to focus traversal operations.
+
+For normal forward and backward traversal, the AWT focus
+implementation determines which Component to focus next based on the
+FocusTraversalPolicy of
+the focus owner's focus cycle root or focus traversal policy provider. If the
+focus owner is a focus cycle root, then it may be ambiguous as to which
+Components represent the next and previous Components to focus during
+normal focus traversal. Thus, the current
+KeyboardFocusManager maintains a reference to the
+"current" focus cycle root, which is global across all contexts. The
+current focus cycle root is used to resolve the ambiguity.
+
+For up-cycle traversal, the focus owner is set to the current focus +owner's focus cycle root, and the current focus cycle root is set to +the new focus owner's focus cycle root. If, however, the current focus +owner's focus cycle root is a top-level window, then the focus owner +is set to the focus cycle root's default component to focus, and the +current focus cycle root is unchanged. +
+For down-cycle traversal, if the current focus owner is a focus cycle +root, then the focus owner is set to the current focus owner's default +component to focus, and the current focus cycle root is set to the +current focus owner. If the current focus owner is not a focus cycle +root, then no focus traversal operation occurs. + + + +
+
+A FocusTraversalPolicy defines the order in which Components within
+a particular focus cycle root or focus traversal policy provider are
+traversed. Instances of FocusTraversalPolicy can be shared across
+Containers, allowing those Containers to implement the same traversal policy.
+FocusTraversalPolicies do not need to be reinitialized when the
+focus-traversal-cycle hierarchy changes.
+
+
+Each FocusTraversalPolicy must define the following
+five algorithms:
+
+
+A FocusTraversalPolicy may optionally provide an
+algorithm for the following:
+
+ Given a Window, the "initial" Component in that Window. The initial + Component will be the first to receive focus when the Window is + first made visible. By default, this is the same as the "default" + Component. ++ +In addition, Swing provides a subclass of
FocusTraversalPolicy,
+InternalFrameFocusTraversalPolicy, which allows developers
+to provide an algorithm for the following:
+
+ + Given a+ +AJInternalFrame, the "initial" Component in that +JInternalFrame. The initial Component is the first to + receive focus when theJInternalFrameis first selected. + By default, this is the same as theJInternalFrame's + default Component to focus. +
FocusTraversalPolicy is installed on a Container using
+Container.setFocusTraversalPolicy. If a policy is not explicitly
+set, then a Container inherits its policy from its nearest focus-cycle-root
+ancestor. Top-levels initialize their focus traversal policies using the context
+default policy. The context default policy is established by using
+KeyboardFocusManager. setDefaultFocusTraversalPolicy.
+
+
+AWT provides two standard FocusTraversalPolicy
+implementations for use by client code.
+
+
ContainerOrderFocusTraversalPolicy: Iterates across the
+ Components in a focus traversal cycle in the order they were added
+ to their Containers. Each Component is tested for fitness using the
+ accept(Component) method. By default, a Component is fit only if it
+ is visible, displayable, enabled, and focusable.
+ DefaultFocusTraversalPolicy: A subclass of
+ ContainerOrderFocusTraversalPolicy which redefines
+ the fitness test. If client code has explicitly set the
+ focusability of a Component by either overriding
+ Component.isFocusTraversable() or
+ Component.isFocusable(), or by calling
+ Component.setFocusable(boolean), then a
+ DefaultFocusTraversalPolicy behaves exactly
+ like a ContainerOrderFocusTraversalPolicy. If,
+ however, the Component is relying on default focusability, then a
+ DefaultFocusTraversalPolicy will reject all
+ Components with non-focusable peers.
+ +Swing provides two additional, standard FocusTraversalPolicy +implementations for use by client code. Each implementation is an +InternalFrameFocusTraversalPolicy. + +
+The figure below shows an implicit focus transfer:
+
+
+Assume the following:
+
+Swing applications, or mixed Swing/AWT applications, that use one of +the standard look and feels, or any other look and feel derived from +BasicLookAndFeel, will use LayoutFocusTraversalPolicy for all +Containers by default. +
+All other applications, including pure AWT applications, will use
+DefaultFocusTraversalPolicy by default.
+
+
+
+ A Container that isn't a focus cycle root has an option to provide a
+ FocusTraversalPolicy of its own. To do so, one needs to set Container's focus
+ traversal policy provider property to true with the call to
+
+
+ Container.setFocusTraversalPolicyProvider(boolean)
+
+
+ To determine whether a Container is a focus traversal policy provider, the
+ following method should be used:
+
+
+ Container.isFocusTraversalPolicyProvider()
+
+
+ If focus traversal policy provider property is set on a focus cycle root, it
+ isn't considered a focus traversal policy provider and behaves just like any
+ other focus cycle root.
+
++ The main difference between focus cycle roots and focus traversal policy + providers is that the latter allow focus to enter and leave them just as all other + Containers. However, children inside focus traversal policy provider are + traversed in the order determined by provider's FocusTraversalPolicy. In order + to enable focus traversal policy providers to behave this way, + FocusTraversalPolicies treat them in the following manner: + +
FocusTraversalPolicy.getComponentAfter or
+ FocusTraversalPolicy.getComponentBefore,
+ next found Component is
+ the first Component of focus traversal policy
+ provider, the Component after the focus traversal policy
+ provider is returned
+ previous found Component is
+ the last Component of focus traversal policy
+ provider, the Component before the focus traversal policy
+ provider is returned
+ FocusTraversalPolicy.getComponentAfter,
+ FocusTraversalPolicy.getComponentAfter
+ method is a traversable Container and it is a focus
+ traversal policy provider, then the default Component of this provider
+ is returned
+ FocusTraversalPolicy.getComponentBefore,
+
+In addition to user-initiated focus traversal, client code can
+initiate a focus traversal operation programmatically. To client code,
+programmatic traversals are indistinguishable from user-initiated
+traversals. The preferred way to initiate a programmatic traversal is
+to use one of the following methods on KeyboardFocusManager:
+
+
KeyboardFocusManager.focusNextComponent()
+ KeyboardFocusManager.focusPreviousComponent()
+ KeyboardFocusManager.upFocusCycle()
+ KeyboardFocusManager.downFocusCycle()
+ +Each of these methods initiates the traversal operation with the +current focus owner. If there is currently no focus owner, then no +traversal operation occurs. In addition, if the focus owner is not a +focus cycle root, then downFocusCycle() performs no traversal +operation. +
+KeyboardFocusManager also supports the following variants
+of these methods:
+
+
KeyboardFocusManager.focusNextComponent(Component)
+ KeyboardFocusManager.focusPreviousComponent(Component)
+ KeyboardFocusManager.upFocusCycle(Component)
+ KeyboardFocusManager.downFocusCycle(Container)
+ +Alternate, but equivalent, APIs are defined on the Component and +Container classes themselves: + +
Component.transferFocus()
+ Component.transferFocusBackward()
+ Component.transferFocusUpCycle()
+ Container.transferFocusDownCycle()
+ KeyboardFocusManager variants, each of these methods
+initiates the traversal operation as though the Component is the focus
+owner, though it need not be.
++Also note that hiding or disabling the focus owner, directly or +indirectly via an ancestor, or making the focus owner non-displayable +or non-focusable, initiates an automatic, forward focus traversal. +While hiding any ancestor, lightweight or heavyweight, will always +indirectly hide its children, only disabling a heavyweight ancestor +will disable its children. Thus, disabling a lightweight ancestor of +the focus owner does not automatically initiate a focus traversal. +
+If client code initiates a focus traversal, and there is no other +Component to focus, then the focus owner remains unchanged. If client +code initiates an automatic focus traversal by hiding the focus owner, +directly or indirectly, or by making the focus owner non-displayable or +non-focusable, and there is no other Component to focus, then the +global focus owner is cleared. If client code initiates an automatic +focus traversal by disabling the focus owner, directly or indirectly, +and there is no other Component to focus, then the focus owner remains +unchanged. + + + +
+A focusable Component can become the focus owner ("focusability") and +participates in keyboard focus traversal ("focus traversability") with +a FocusTraversalPolicy. There is no separation of these two concepts; +a Component must either be both focusable and focus traversable, or +neither. + +A Component expresses this state via the isFocusable() method. By +default, all Components return true from this method. Client code can +change this default by calling Component.setFocusable(boolean). + + + +
+To support palette windows and input methods, client code can prevent +a Window from becoming the focused Window. By transitivity, this +prevents the Window or any of its descendants from becoming the focus +owner. Non-focusable Windows may still own Windows that are +focusable. By default, every Frame and Dialog is focusable. Every +Window which is not a Frame or Dialog, but whose nearest owning Frame +or Dialog is showing on the screen, and which has at least one +Component in its focus traversal cycle, is also focusable by +default. To make a Window non-focusable, use +Window.setFocusableWindowState(false). +
+If a Window is non-focusable, this restriction is enforced when the
+KeyboardFocusManager sees a WINDOW_GAINED_FOCUS
+event for the Window. At this point, the focus change is rejected and
+focus is reset to a different Window. The rejection recovery scheme
+is the same as if a VetoableChangeListener rejected the
+focus change. See Focus
+and VetoableChangeListener.
+
+Because the new focus implementation requires that KeyEvents intended +for a Window or its descendants be proxied through a child of the +Window's owner, and because this proxy must be mapped on X11 in order +to receive events, a Window whose nearest owning Frame or Dialog is +not showing could never receive KeyEvents on X11. To support this +restriction, we have made a distinction between a Window's "window +focusability" and its "window focusability state". A Window's +focusability state is combined with the showing state of the Window's +nearest owning Frame or Dialog to determine the Window's focusability. +By default, all Windows have a focusability state of true. Setting a +Window's focusability state to false ensures that it will not become +the focused Window regardless of the showing state of its nearest +owning Frame or Dialog. +
+Swing allows applications to create JWindows with null owners. Swing +constructs all such JWindows so that they are owned by a private, +hidden Frame. Because the showing state of this Frame will always be +false, a JWindow constructed will a null owner can never be the +focused Window, even if it has a Window focusability state of true. +
+If the focused Window is made non-focusable, then the AWT will attempt +to focus the most recently focused Component of the Window's +owner. The Window's owner will thus become the new focused Window. If +the Window's owner is also a non-focusable Window, then the focus +change request will proceed up the ownership hierarchy recursively. +Since not all platforms support cross-Window focus changes (see +Requesting Focus), it is possible that +all such focus change requests will fail. In this case, the global +focus owner will be cleared and the focused Window will remain unchanged. + + +
+A Component can request that it become the focus owner by calling
+Component.requestFocus(). This initiates a permanent
+focus transfer to the Component only if the Component is displayable,
+focusable, visible and all of its ancestors (with the exception of the
+top-level Window) are visible. The request will be immediately denied if
+any of these conditions is not met. A disabled Component may be
+the focus owner; however, in this case, all KeyEvents will be discarded.
+
+The request will also be denied if the Component's top-level Window is +not the focused Window and the platform does not support requesting +focus across Windows. If the request is denied for this reason, the +request is remembered and will be granted when the Window is later +focused by the user. Otherwise, the focus change request changes the +focused Window as well. +
+There is no way to determine synchronously whether a focus change
+request has been granted. Instead, client code must install a
+FocusListener on the Component and watch for the delivery of a
+FOCUS_GAINED event. Client code must not assume that
+the Component is the focus owner until it receives this event.
+The event may or may not be delivered before requestFocus()
+returns. Developers must not assume one behavior or the other.
+
+The AWT supports type-ahead if all focus change requests are made on +the EventDispatchThread. If client code requests a focus change, and +the AWT determines that this request might be granted by the native +windowing system, then the AWT will notify the current +KeyboardFocusManager that is should enqueue all KeyEvents with a +timestamp later than the that of the event currently being handled. +These KeyEvents will not be dispatched until the new Component becomes +the focus owner. The AWT will cancel the delayed dispatching request +if the focus change does not succeed at the native level, if the +Component's peer is disposed, or if the focus change is vetoed by a +VetoableChangeListener. KeyboardFocusManagers are not required to +support type-ahead if a focus change request is made from a thread +other than the EventDispatchThread. +
+Because Component.requestFocus() cannot be implemented
+consistently across platforms, developers are encouraged to use
+Component.requestFocusInWindow() instead. This method
+denies cross-Window focus transfers on all platforms automatically.
+By eliminating the only platform-specific element of the focus transfer,
+this method achieves consistent cross-platform behavior.
+
+In addition, requestFocusInWindow() returns a boolean value.
+If 'false' is returned, the request is guaranteed to fail. If 'true' is
+returned, the request will succeed unless it is vetoed, or an
+extraordinary event, such as disposal of the Component's peer, occurs
+before the request can be granted by the native windowing
+system. Again, while a return value of 'true' indicates that the
+request is likely to succeed, developers must never assume that this
+Component is the focus owner until this Component receives a
+FOCUS_GAINED event.
+
+If client code wants no Component in the application to be the focus
+owner, it can call the method KeyboardFocusManager.
+clearGlobalFocusOwner() on the current
+KeyboardFocusManager. If there exists a focus owner
+when this method is called, the focus owner will receive a permanent
+FOCUS_LOST event. After this point, the AWT
+focus implementation will discard all KeyEvents until the user or
+client code explicitly sets focus to a Component.
+
+The Component class also supports variants of requestFocus and
+requestFocusInWindow that allow client code to specify
+a temporary state.
+See Temporary FocusEvents
+
+
+
+Client code can listen to changes in context-wide focus state, or to +changes in focus-related state in Components, via +PropertyChangeListeners. +
+The KeyboardFocusManager supports the following properties:
+
+
focusOwner: the focus owner
+ focusedWindow: the focused Window
+ activeWindow: the active Window
+ defaultFocusTraversalPolicy: the default focus
+ traversal policy
+ forwardDefaultFocusTraversalKeys: the Set of default
+ FORWARD_TRAVERSAL_KEYS
+ backwardDefaultFocusTraversalKeys: the Set of default
+ BACKWARD_TRAVERSAL_KEYS
+ upCycleDefaultFocusTraversalKeys: the Set of default
+ UP_CYCLE_TRAVERSAL_KEYS
+ downCycleDefaultFocusTraversalKeys: the Set of default
+ DOWN_CYCLE_TRAVERSAL_KEYS
+ currentFocusCycleRoot: the current focus cycle root
+
+A PropertyChangeListener installed on the current
+KeyboardFocusManager will only see these changes within
+the KeyboardFocusManager's context, even though the
+focus owner, focused Window, active Window, and current focus cycle
+root comprise the global focus state shared by all contexts.
+We believe this is less intrusive than requiring client code to pass
+a security check before installing a PropertyChangeListener.
+
+Component supports the following focus-related properties: + +
focusable: the Component's focusability
+ focusTraversalKeysEnabled: the Component's
+ focus traversal keys enabled state
+ forwardFocusTraversalKeys: the Component's Set of
+ FORWARD_TRAVERSAL_KEYS
+ backwardFocusTraversalKeys: the Component's Set of
+ BACKWARD_TRAVERSAL_KEYS
+ upCycleFocusTraversalKeys: the Component's Set of
+ UP_CYCLE_TRAVERSAL_KEYS
+ +In addition to the Component properties, Container supports the +following focus-related properties: + +
downCycleFocusTraversalKeys: the Container's Set of
+ DOWN_CYCLE_TRAVERSAL_KEYS
+ focusTraversalPolicy: the Container's focus
+ traversal policy
+ focusCycleRoot: the Container's focus-cycle-root state
+ +In addition to the Container properties, Window supports the following +focus-related property: + +
focusableWindow: the Window's focusable Window state
+
+Also note that a PropertyChangeListener installed on a
+Window will never see a PropertyChangeEvent for the
+focusCycleRoot property.
+A Window is always a focus cycle root; this property cannot change.
+
+The KeyboardFocusManager also supports
+VetoableChangeListeners for the following properties:
+
+
+VetoableChangeListeners are notified of the state change before the +change is reflected in the KeyboardFocusManager. Conversely, +PropertyChangeListeners are notified after the change is reflected. +It follows that all VetoableChangeListeners will be notified before +any PropertyChangeListener. +
+VetoableChangeListeners must be idempotent, and must veto both loss
+and gain events for a particular focus change (e.g., both
+FOCUS_LOST and FOCUS_GAINED). For example,
+if a VetoableChangeListener vetoes a FOCUS_LOST
+event, a KeyboardFocusManager is not required to search the
+EventQueue and remove the associated pending
+FOCUS_GAINED event. Instead, the
+KeyboardFocusManager is free to attempt to
+dispatch this event and it is the responsibility of the
+VetoableChangeListener to veto it as well. In addition,
+during processing of the FOCUS_GAINED event, the
+KeyboardFocusManager may attempt to resync the global
+focus state by synthesizing another FOCUS_LOST event.
+This event must be vetoed just as the first FOCUS_LOST event was.
+
+A KeyboardFocusManager may not hold any locks while
+notifying PropertyChangeListeners of a state change.
+This requirement is relaxed for VetoableChangeListeners,
+however. Therefore, client-definied VetoableChangeListeners
+should avoid acquiring additional locks inside
+vetoableChange(PropertyChangeEvent) as this may lead to deadlock.
+
+If a focus or activation change is rejected, the KeyboardFocusManager
+will initiate rejection recovery as follows:
+
+
KeyboardFocusManager will clear
+ the global focus owner.
+ KeyboardFocusManager
+ will clear the global focus owner.
+ VetoableChangeListeners must be careful to avoid vetoing focus
+changes initiated as a result of veto rejection recovery. Failure
+to anticipate this situation could lead to an infinite cycle of
+vetoed focus changes and recovery attempts.
+
+
+
++On some native windowing systems, the Z-order of a Window can affect +its focused or active (if applicable) state. On Microsoft Windows, the +top-most Window is naturally the focused Window as well. However, on +Solaris, many window managers use a point-to-focus model that ignores +Z-order in determining the focused Window. + +When focusing or activating Windows, the AWT adheres to the UI +requirements of the native platform. Therefore, the focus behavior of +Z-order-related methods such as: +
Window.toFront()
+ Window.toBack()
+ Window.show()
+ Window.hide()
+ Window.setVisible(boolean)
+ Window.dispose()
+ Frame.setState(int)
+ Window.toFront():Window.toBack():Window.show()/Window.setVisible(true)/Frame.setState(NORMAL):Window.hide()/Window.setVisible(false)/Window.dispose()/
+ Frame.setState(ICONIFIED):
+KeyboardFocusManagers are pluggable at the browser context
+level. Client code can subclass KeyboardFocusManager or
+DefaultKeyboardFocusManager to modify the way that WindowEvents
+related to focus, FocusEvents, and KeyEvents are handled and
+dispatched, and to examine and modify the global focus state. A custom
+KeyboardFocusManager can also reject focus changes at a more
+fundamental level then a FocusListener or WindowListener ever could.
+
+While giving a developer ultimate control over the focus model,
+replacing the entire KeyboardFocusManager is a difficult process
+requiring a thorough understanding of the peer focus layer.
+Fortunately, most applications do not need this much control.
+Developers are encouraged to use KeyEventDispatchers,
+KeyEventPostProcessors, FocusTraversalPolicies,
+VetoableChangeListeners, and other concepts discussed in this document
+before resorting to a full replacement of the KeyboardFocusManager.
+
+First note that, because unhindered access to Components in other
+contexts represents a security hole, the SecurityManager must grant a
+new permission, "replaceKeyboardFocusManager", before client code is
+permitted to replace the KeyboardFocusManager with an arbitrary
+subclass instance. Because of the security check, replacing the
+KeyboardFocusManager is not an option for applications that will be
+deployed in environments with a SecurityManager, such as applets in a
+browser.
+
+Once installed, a KeyboardFocusManager instance has
+access to the global focus state via a set of protected functions.
+The KeyboardFocusManager can only call these functions
+if it is installed in the calling thread's context. This ensures
+that malicious code cannot circumvent the security check in
+KeyboardFocusManager.setCurrentFocusManager.
+A KeyboardFocusManager should always work with
+the global focus state instead of the context focus state.
+Failure to do this will lead to incorrect behavior of the
+KeyboardFocusManager.
+
+The primary responsibility of a KeyboardFocusManager
+is the dispatch of the following events:
+
+
KeyEvents
+ FocusEvents
+ WindowEvent.WINDOW_GAINED_FOCUS
+ WindowEvent.WINDOW_LOST_FOCUS
+ WindowEvent.WINDOW_ACTIVATED
+ WindowEvent.WINDOW_DEACTIVATED
+ KeyboardFocusManager
+with all of the above events except WINDOW_ACTIVATED
+and WINDOW_DEACTIVATED. The KeyboardFocusManager
+must synthesize WINDOW_ACTIVATED and
+WINDOW_DEACTIVATED events when appropriate and target them
+accordingly.
+
+The KeyboardFocusManager may need to retarget the events
+provided by the peer layer to its own notion of the focus owner or
+focused Window:
+
FOCUS_LOST event must be retargeted to the focus
+ owner. Again, this is necessary because the peer layer is
+ unaware of lightweight Components.
+ WINDOW_LOST_FOCUS event must be retargeted to
+ the focused Window. The implementation of the Window class
+ may cause the native focused Window to differ from the Java
+ focused Window.
+
+A KeyboardFocusManager must ensure proper event ordering,
+and a 1-to-1 correspondence between an event and its opposite event type.
+The peer layer does not make any of these guarantees. For example, it is
+possible for the peer layer to send a FOCUS_GAINED
+event before a WINDOW_GAINED_FOCUS event.
+The KeyboardFocusManager is responsible for
+ensuring that the WINDOW_GAINED_FOCUS event is dispatched
+before the FOCUS_GAINED event.
+
+Before redispatching an event via KeyboardFocusManager.
+redispatchEvent, a KeyboardFocusManager
+must attempt to update the global focus state. Typically, this
+is done using one of the KeyboardFocusManager.setGlobal*
+methods; however, an implementation is free to implement its own methods.
+After attempting an update, the KeyboardFocusManager
+must verify that the global focus state change
+was not rejected. A rejection is detected when a call to the
+corresponding getGlobal* method returns a value different than the
+value just set. Rejections occur in three standard cases:
+
KeyboardFocusManager attempts
+ to set the global focus owner to a non-focusable Component.
+ KeyboardFocusManager attempts
+ to set the global focused Window to a non-focusable Window.
+ VetoableChangeListener.
+
+Client-defined implementations of KeyboardFocusManager
+can adjust the set of focus transfers which are rejected by overriding the
+accessor and mutator methods for the global focus state.
+
+If a request to change the global focus state is rejected, the
+KeyboardFocusManager must discard the event which prompted
+the focus change request. The Component to which the event was targeted
+must not receive the event.
+
+The KeyboardFocusManager is also expected to initiate rejection
+recovery as outlined in Focus
+and VetoableChangeListener.
+
+ Finally, a KeyboardFocusManager must handle the following set of + special cases: +
WINDOW_GAINED_FOCUS event, the
+ KeyboardFocusManager must set focus to the
+ appropriate child Component of the Window. If a child
+ Component of the Window previously requested focus,
+ but the focus change was rejected because the platform
+ does not support cross-Window focus change requests,
+ then focus should be set to that child Component.
+ Otherwise, if the Window has never been focused, focus should be
+ set to the Window's initial Component to focus. If the Window was
+ previously focused, focus should be set to the Window's most
+ recent focus owner.
+ KeyboardFocusManager must ensure that the
+ opposite Component or Window are as accurate as the native
+ windowing platform permits. For example, the
+ KeyboardFocusManager may need to
+ retarget the opposite Component to a lightweight child of the
+ heavyweight initially specified by the peer layer.
+ null, it is acceptable for the
+ KeyboardFocusManager to propagate
+ this value. null indicates that it is highly
+ probably that no other Component or Window was involved
+ in the focus or activation change. Because of platform
+ limitations, this computation may be
+ subject to a heuristic and could be incorrect. Nevertheless, this
+ heuristic will be the best possible guess which the peer layer
+ could make.
+ Cross-platform changes: +
DefaultFocusTraversalPolicy for all AWT Containers
+ will preserve the traversal order of previous releases.
+ Window.toFront() and Window.toBack()
+ now perform no operation if the Window is not visible.
+ Previously, the behavior was platform-dependent.
+ Components
+ will no longer see KeyEvents that map to focus
+ traversal operations, and
+ Component.handleEvent() will no longer be invoked
+ for such events. Previously, AWT Components saw these events
+ and had an opportunity to consume them before AWT
+ initiated focus traversal. Code that requires this
+ functionality should instead disable focus traversal keys on
+ its Components and handle focus traversal
+ itself. Alternately, the code can use an
+ AWTEventListener or
+ KeyEventDispatcher to pre-listen to all
+ KeyEvents.
+ Changes specific to Microsoft Windows: +
Window.toBack() changes the focused Window to
+ the top-most Window after the Z-order change.
+ requestFocus() now allows cross-Window focus
+ change requests in all cases. Previously, requests were granted
+ for heavyweights, but denied for lightweights.
+
+ This document, together with the API documentation for modality-related
+ classes (such as java.awt.Dialog), briefly describes the new
+ modality features and how to use them. It contains the following sections:
+
+ Document - a window without an owner that, together with + all its child hierarchy, may be operated on as a single self-contained + document. + Every window belongs to some document — its root can be found as + the closest ancestor window without an owner. +
+ + Modal blocked window - a window, that: +
++
+ Warning! Some window managers allow users to change the window + Z-order in an arbitrary way — in that case the last requirement + may not be met. +
+
+ Modal dialog - a dialog that blocks some windows while it is + visible. The blocked windows are determined according to the dialog's + scope of blocking. +
+ Modal excluded window - a window that stays unblocked + while the modal dialog is visible. If a window is modal excluded + then all its owned windows and child components are also excluded. +
+ Scope of blocking (SB) - the set of windows (instances of
+ java.awt.Window and all derived classes) that are blocked by
+ the modal dialog while it is visible.
+
+
+ + +
+ Note: Everywhere in this document the notion of "window" is equal + to a top-level window in the Java programming language — in other words + an instance ofjava.awt.Windowor any descendant class. +
+ There are four supported modality types : +
+
+ Modality priority is arranged by the strength of blocking: modeless, + document-modal, application-modal and toolkit-modal. This arrangement + is used when determining what dialog should remain unblocked if two + are visible and block each other. It naturally reflects the nesting + of a dialog's scope of blocking (SB): a modeless dialog has an empty SB, + a document-modal dialog's SB is complete in some applications, + and all the applications are run in one toolkit.
+ Notes about owners: +
Dialog is a class derived from
+ Window, a Dialog instance automatically
+ becomes the root of the document if it has no owner. Thus, if
+ such a dialog is document-modal, its scope of blocking is empty
+ and it behaves the same way as a modeless dialog.
+ +
+ + +
+ Implementation note: Changing the modality type for a visible + dialog may have no effect until it is hidden and then shown again. +
+ Showing the window or modeless dialog: "F"
+ All the visible modal dialogs are looked through — if F is from the SB
+ of one of them, it becomes blocked by it. If there are several such
+ dialogs, the first shown is used. If no such dialogs exist, F remains
+ unblocked.
+
+ Showing the modal dialog: "M"
+ When modal dialog M is shown, all the visible windows fall into one of
+ three distinct groups:
+
+ After the modal dialog M is shown, it becomes blocked by the first shown + dialog from the first group (if there are any), all the windows from the + second one become blocked by M, and all the windows from the third group + remain untouched. +
+ In typical cases, when no child dialogs are shown before their owners, + this rule can be simplified. (The following, simplified case, may + leave out some details). +
+ Showing the document-modal dialog: "M"
+ All the visible application- and toolkit-modal dialogs are looked
+ through — if M is from the SB of one of them,
+ it becomes blocked by it. If there are several such dialogs,
+ the first shown is used. If no such dialogs exist, M remains unblocked.
+
+ Showing the application-modal dialog: "M"
+ All the visible toolkit-modal dialogs are looked through —
+ if M is from the SB of one of them, it becomes blocked by it.
+ If there are several such dialogs, the first shown is used.
+ If no such dialogs exist, M remains unblocked.
+
+ Showing the toolkit-modal dialog: "M"
+ M remains unblocked.
+
+ +
+| current/shown | +frame & modeless | +document | +application | +toolkit | +
| - | +- | +- | +- | +- | +
| document | +blocked | +- | +- | +- | +
| application | +blocked | +blocked | +- | +- | +
| toolkit | +blocked | +blocked | +blocked | +- | +
+ After the modal dialog is shown, all the windows from its SB are blocked, + except those that block this modal dialog. +
+ Hiding the window or modeless dialog: "F"
+ If F was blocked by any modal dialog M, it becomes unblocked and is
+ removed from M's blocked windows list.
+
+ Hiding the modal dialog: "M"
+ If M was blocked by any other modal dialog, for example, "N",
+ it becomes unblocked and
+ is removed from N's blocked windows list. Then, all the windows and dialogs
+ blocked by M become unblocked, and after that the same checks
+ (as in Showing the modal dialog: "M")
+ are performed for each of them in the order they were initially shown.
+
+
+
+ There are two modal exclusion types introduced as of JDK 6 +
+
+
++ + +
+ Implementation note: Changing the modal exclusion type for a visible window + may have no effect until it is hidden and then shown again. +
+ Always-On-Top
+ When a modal dialog that is not always-on-top blocks an always-on-top window,
+ their relative Z-order is unspecified and platform-dependent.
+
+ The toFront() and toBack() methods
+ A modal dialog should always be above all its blocked windows. Thus, if a blocked
+ window is brought to the front, its blocking dialog, if any, is also brought to the
+ front and remains above the blocked window. Likewise, if a modal dialog is sent to
+ the back, all of its blocked windows are sent to the back to keep them below the
+ blocking dialog.
+
+ Minimizing, maximizing and closing blocked windows
+ When a modal dialog blocks a window, the user may not be able to maximize or
+ minimize the blocked window— however, the actual behavior is unspecified
+ and platform-dependent. In any case, the user can't close the blocked window
+ interactively— but it can be closed programmatically by calling the
+ setVisible(false) or dispose() methods on the blocked
+ window.
+
+ Blocked windows activations
+ When the user selects a blocked window, it may be brought to the front, along
+ with the blocking modal dialog which would then become the active window—
+ however, the actual behavior is unspecified and platform-dependent.
+
+ Hiding a modal dialog
+ When the modal dialog that currently has focus is hidden, it is unspecified
+ and platform-dependent, which other window will become the active window.
+ Any of the following may become the active window:
+
Window, which was active before this modal dialog gained
+ focus - if the owner of the modal dialog is absent or is blocked.
+
+ A special AWTPermission, "toolkitModality",
+ is required to show toolkit-modal
+ dialogs. This would prevent, for example, blocking a browser or
+ Java Web Start (JWS) by modal dialogs shown from applets.
+
+ The same permission is required to exclude a window from toolkit modality. + This would prevent, for example, a dialog shown from an applet not to be + blocked by a browser's or JWS's modal dialog. + + +
+ Two java.awt.Toolkit methods allow you to check whether
+ the current platform supports specific modality features:
+
isModalityTypeSupported(modalityType)isModalExclusionTypeSupported(modalExclusionType)
+ The default modality type is application-modal. It is used by the API
+ calls: Dialog.setModal(true),
+ Dialog(owner, true), etc. Prior to JDK 6
+ the default type was toolkit-modal,
+ but the only distinction between application- and toolkit-modality is for
+ applets and applications launched from Java Web Start.
+
+
+
+
+ |
+
+ 
+ + |
+
+
+ |
+
+ 
+ + |
+
+
+ |
+
+ 
+ + |
+
+
+ |
+
+ 
+ + |
+
Provides classes and interfaces for the input method framework. +This package enables text editing components to receive text input +through input methods. Input methods are software components that let +the user enter text in ways other than simple typing on a keyboard. +They are commonly used to enter Japanese, Chinese, or Korean - +languages using thousands of different characters - on keyboards with +far fewer keys. However, the framework also supports input methods +for other languages and the use of entirely different input +mechanisms, such as handwriting or speech recognition.
+ +For overviews, tutorials, examples, guides, and tool +documentation, please see:
+ + + +@since 1.2 + + diff --git a/out/production/classes1/awt/im/spi/package.html b/out/production/classes1/awt/im/spi/package.html new file mode 100644 index 0000000000000000000000000000000000000000..58e77ee257a4e4861dcd40aca9d55ceb9b4a643e --- /dev/null +++ b/out/production/classes1/awt/im/spi/package.html @@ -0,0 +1,126 @@ + + + + + + +Provides interfaces that enable the development of input methods +that can be used with any Java runtime environment. Input methods are +software components that let the user enter text in ways other than +simple typing on a keyboard. They are commonly used to enter +Japanese, Chinese, or Korean - languages using thousands of different +characters - on keyboards with far fewer keys. However, this package +also allows the development of input methods for other languages and +the use of entirely different input mechanisms, such as handwriting +recognition.
+ +Input methods are packaged as installed extensions, as specified +by the Extension +Mechanism. The main JAR file of an input method must contain the +file:
+ +META-INF/services/java.awt.im.spi.InputMethodDescriptor+ +
The file should contain a list of fully-qualified class names, one
+per line, of classes implementing the
+java.awt.im.spi.InputMethodDescriptor interface. Space
+and tab characters surrounding each name, as well as blank lines, are
+ignored. The comment character is '#'
+(\u0023); on each line all characters following the
+first comment character are ignored. The file must be encoded in
+UTF-8.
For example, if the fully-qualified name of the class that
+implements java.awt.im.spi.InputMethodDesciptor for the
+Foo input method is
+com.sun.ime.FooInputMethodDescriptor, the file
+META-INF/services/java.awt.im.spi.InputMethodDescriptor
+contains a line:
com.sun.ime.FooInputMethodDescriptor+ +
The input method must also provide at least two classes: one class
+implementing the java.awt.im.spi.InputMethodDescriptor
+interface, one class implementing the
+java.awt.im.spi.InputMethod interface. The input method
+should separate the implementations for these interfaces, so that
+loading of the class implementing InputMethod can be
+deferred until actually needed.
The input method framework will usually defer loading of input
+method classes until they are absolutely needed. It loads only the
+InputMethodDescriptor implementations during AWT
+initialization. It loads an InputMethod implementation
+when the input method has been selected.
The Java input method framework intends to support all +combinations of input methods (host input methods and Java input +methods) and components (peered and lightweight). However, because of +limitations in the underlying platform, it may not always be possible +to enable the communication between Java input methods and peered AWT +components. Support for this specific combination is therefore +platform dependent. In Sun's Java SE Runtime Environments, this +combination is supported on Windows, but not on Solaris.
+ +For overviews, tutorials, examples, guides, and tool +documentation, please see:
+ + + +@since JDK1.3 + + diff --git a/out/production/classes1/awt/image/package.html b/out/production/classes1/awt/image/package.html new file mode 100644 index 0000000000000000000000000000000000000000..5f47da4e4df82471b1697450fba51b0b4911cfac --- /dev/null +++ b/out/production/classes1/awt/image/package.html @@ -0,0 +1,58 @@ + + + + ++Some components fire events when a user interacts with the components. The AWTEvent +class and its subclasses are used to represent the events that AWT components can fire. See +AWTEvent for a description of the AWT event model. +
+A container is a component that can contain components and other containers. A con +tainer can also have a layout manager that controls the visual placement of components in the +container. The AWT package contains several layout manager classes and an interface for +building your own layout manager. See Container and LayoutManager for more information. +
+Each {@code Component} object is limited in its maximum size and +its location because the values are stored as an integer. +Also, a platform may further restrict maximum size and location +coordinates. The exact maximum values are dependent on the platform. +There is no way to change these maximum values, either in Java +code or in native code. +These limitations also impose restrictions on component layout. +If the bounds of a Component object exceed a platform limit, +there is no way to properly arrange them within a Container object. +The object's bounds are defined by any object's coordinate +in combination with its size on a respective axis. + + +
PropertyEditor interface, a bean developer can
+provide an editor for this special type.
+
++To minimize the resources used by a bean, the classes used by bean editors are loaded only +when the bean is being edited. They are not needed while the bean is running in an application +and therefore not loaded. This information is kept in what's called a bean-info (see {@link java.beans.BeanInfo}). + +
+Unless explicitly stated, null values or empty Strings are not valid +parameters for the methods in this package. You may expect to see +exceptions if these parameters are used. + + +
java.beans package provides support for
+long-term persistence -- reading and
+writing a bean as a textual representation of its property values.
+The property values are treated as beans,
+and are recursively read or written to capture
+their publicly available state.
+This approach is suitable for long-term storage
+because it relies only on public API,
+rather than the likely-to-change private implementation.
+
+++ +
+Note: +The persistence scheme cannot automatically instantiate +custom inner classes, such as you might use for event handlers. +By using the {@link java.beans.EventHandler} class +instead of inner classes for custom event handlers, +you can avoid this problem. +
+
+ +You read and write beans in XML format using the +{@link java.beans.XMLDecoder} +and +{@link java.beans.XMLEncoder} +classes, respectively. +One notable feature of the persistence scheme is that +reading in a bean requires no special knowledge of the bean. + +
+Writing out a bean, on the other hand,
+sometimes requires special knowledge of the bean's type.
+If the bean's state can be
+expressed using only the no-argument constructor and
+public getter and setter methods for properties,
+no special knowledge is required.
+Otherwise, the bean requires a custom persistence delegate --
+an object that is in charge of writing out beans of a particular type.
+All classes provided in the JDK that descend
+from java.awt.Component,
+as well as all their properties,
+automatically have persistence delegates.
+
+
+
+If you need (or choose) to provide a persistence delegate for a bean,
+you can do so either by using a
+{@link java.beans.DefaultPersistenceDelegate}
+instance
+or by creating your own subclass of PersistenceDelegate.
+If the only reason a bean needs a persistence delegate
+is because you want to invoke the bean's constructor with
+property values as arguments,
+you can create the bean's persistence delegate
+with the one-argument
+DefaultPersistenceDelegate
+constructor.
+Otherwise,
+you need to implement your own persistence delegate,
+for which you're likely to need the following classes:
+
+
Statements and Expressions
+ are necessary to create the bean
+ and restore its state.
+Statement
+ used for methods that return a value.
+
+Once you create a persistence delegate,
+you register it using the
+setPersistenceDelegate method of
+XMLEncoder.
+
+
+
+
+
+
diff --git a/out/production/classes1/classes.iml b/out/production/classes1/classes.iml
new file mode 100644
index 0000000000000000000000000000000000000000..b107a2dd81165eaaf682ad3da030668b937fbb6c
--- /dev/null
+++ b/out/production/classes1/classes.iml
@@ -0,0 +1,11 @@
+
+
java.util.Optional and
+java.time.LocalDateTime, are value-based. Instances of a
+value-based class:
+equals,
+ hashCode, and toString which are computed
+ solely from the instance's state and not from its identity or the state
+ of any other object or variable;==) between instances, identity hash code of
+ instances, or synchronization on an instances's intrinsic lock;equals(), not
+ based on reference equality (==);x and y that are equal
+ according to equals() in any computation or method
+ invocation should produce no visible change in behavior.
+ A program may produce unpredictable results if it attempts to distinguish two + references to equal values of a value-based class, whether directly via reference + equality or indirectly via an appeal to synchronization, identity hashing, + serialization, or any other identity-sensitive mechanism. Use of such + identity-sensitive operations on instances of value-based classes may have + unpredictable effects and should be avoided.
+ + diff --git a/out/production/classes1/lang/doc-files/capchi.gif b/out/production/classes1/lang/doc-files/capchi.gif new file mode 100644 index 0000000000000000000000000000000000000000..8a506ebfb89bef96f3cbb29af83e468add67a301 Binary files /dev/null and b/out/production/classes1/lang/doc-files/capchi.gif differ diff --git a/out/production/classes1/lang/doc-files/capiota.gif b/out/production/classes1/lang/doc-files/capiota.gif new file mode 100644 index 0000000000000000000000000000000000000000..42e74365b648cf7c6ed53a02b6634cbec424fbf0 Binary files /dev/null and b/out/production/classes1/lang/doc-files/capiota.gif differ diff --git a/out/production/classes1/lang/doc-files/capsigma.gif b/out/production/classes1/lang/doc-files/capsigma.gif new file mode 100644 index 0000000000000000000000000000000000000000..f75c3553b8eec054cc9e17284bc8ec1ee1bc89d6 Binary files /dev/null and b/out/production/classes1/lang/doc-files/capsigma.gif differ diff --git a/out/production/classes1/lang/doc-files/captheta.gif b/out/production/classes1/lang/doc-files/captheta.gif new file mode 100644 index 0000000000000000000000000000000000000000..96b4c5022d99b4e1de7f6b8432207cf30601cf70 Binary files /dev/null and b/out/production/classes1/lang/doc-files/captheta.gif differ diff --git a/out/production/classes1/lang/doc-files/capupsil.gif b/out/production/classes1/lang/doc-files/capupsil.gif new file mode 100644 index 0000000000000000000000000000000000000000..66ea7d424966a722c3679a022e9c480cfe6e66c0 Binary files /dev/null and b/out/production/classes1/lang/doc-files/capupsil.gif differ diff --git a/out/production/classes1/lang/doc-files/chi.gif b/out/production/classes1/lang/doc-files/chi.gif new file mode 100644 index 0000000000000000000000000000000000000000..e4555582cd9fb8d55b51b5027afc252e5177d480 Binary files /dev/null and b/out/production/classes1/lang/doc-files/chi.gif differ diff --git a/out/production/classes1/lang/doc-files/iota.gif b/out/production/classes1/lang/doc-files/iota.gif new file mode 100644 index 0000000000000000000000000000000000000000..d2dfc0d6ec0703a9ec2cb80aa0fb91732c712a9a Binary files /dev/null and b/out/production/classes1/lang/doc-files/iota.gif differ diff --git a/out/production/classes1/lang/doc-files/javalang.doc.anc21.gif b/out/production/classes1/lang/doc-files/javalang.doc.anc21.gif new file mode 100644 index 0000000000000000000000000000000000000000..7fe160aa6e894f308a51bc5ef6154a2768e96e34 Binary files /dev/null and b/out/production/classes1/lang/doc-files/javalang.doc.anc21.gif differ diff --git a/out/production/classes1/lang/doc-files/javalang.doc.anc38.gif b/out/production/classes1/lang/doc-files/javalang.doc.anc38.gif new file mode 100644 index 0000000000000000000000000000000000000000..bccccfc5471d7fe8ddf0f1eccea503d6de26a0a6 Binary files /dev/null and b/out/production/classes1/lang/doc-files/javalang.doc.anc38.gif differ diff --git a/out/production/classes1/lang/doc-files/javalang.doc.anc40.gif b/out/production/classes1/lang/doc-files/javalang.doc.anc40.gif new file mode 100644 index 0000000000000000000000000000000000000000..bea4d55b8d89878539643a50009000ff4334aaa4 Binary files /dev/null and b/out/production/classes1/lang/doc-files/javalang.doc.anc40.gif differ diff --git a/out/production/classes1/lang/doc-files/javalang.doc.anc41.gif b/out/production/classes1/lang/doc-files/javalang.doc.anc41.gif new file mode 100644 index 0000000000000000000000000000000000000000..e2799cd8570eb56ce50340af7c2b81468a521f98 Binary files /dev/null and b/out/production/classes1/lang/doc-files/javalang.doc.anc41.gif differ diff --git a/out/production/classes1/lang/doc-files/sigma1.gif b/out/production/classes1/lang/doc-files/sigma1.gif new file mode 100644 index 0000000000000000000000000000000000000000..cd4939b672a10f6dccbd67715280cea74990a72c Binary files /dev/null and b/out/production/classes1/lang/doc-files/sigma1.gif differ diff --git a/out/production/classes1/lang/doc-files/theta.gif b/out/production/classes1/lang/doc-files/theta.gif new file mode 100644 index 0000000000000000000000000000000000000000..f953e4687c83eb9f1acd78fc5f0772e5355e2994 Binary files /dev/null and b/out/production/classes1/lang/doc-files/theta.gif differ diff --git a/out/production/classes1/lang/doc-files/upsilon.gif b/out/production/classes1/lang/doc-files/upsilon.gif new file mode 100644 index 0000000000000000000000000000000000000000..f8a2b3389f27abf4a7a8593e1fa193b2e606df46 Binary files /dev/null and b/out/production/classes1/lang/doc-files/upsilon.gif differ diff --git a/out/production/classes1/lang/instrument/package.html b/out/production/classes1/lang/instrument/package.html new file mode 100644 index 0000000000000000000000000000000000000000..e6839e52f9b87745272c1bd3ef82c487a8c15b24 --- /dev/null +++ b/out/production/classes1/lang/instrument/package.html @@ -0,0 +1,281 @@ + + + + + + + + + + +Provides services that allow Java programming language agents to instrument programs running on the JVM. +The mechanism for instrumentation is modification of the byte-codes of methods. + ++An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the +agent class which will be loaded to start the agent. For implementations that support a command-line +interface, an agent is started by specifying an option on the command-line. +Implementations may also support a mechanism to start agents some time after the VM has +started. For example, an implementation may provide a mechanism that allows a tool to +attach to a running application, and initiate the loading of the tool's agent into +the running application. The details as to how the load is initiated, is implementation +dependent. + +
+An implementation is not required to provide a way to start agents from the +command-line interface. On implementations that do provide a way to start agents +from the command-line interface, an agent is started by adding this option to +the command-line: +
++jarpath is the path to the agent JAR file. +options is the agent options. +This switch may be used multiple times on the same command-line, +thus creating multiple agents. +More than one agent may use the same jarpath. +An agent JAR file must conform to the JAR file specification. + +-javaagent:jarpath[=options] +
+The manifest of the agent JAR file must contain the attribute Premain-Class. The
+value of this attribute is the name of the agent class. The agent class must implement a
+public static premain method similar in principle to the main application
+entry point. After the Java Virtual Machine (JVM) has initialized, each premain method
+will be called in the order the agents were specified, then the real application
+main method will be called.
+Each premain method must return in order for the startup sequence to proceed.
+
+
+The premain method has one of two possible signatures. The JVM first attempts to
+invoke the following method on the agent class:
+
+
+public static void
+premain(String agentArgs, Instrumentation inst);
+
+
+
++If the agent class does not implement this method then the JVM will attempt to invoke: + +
+public static void
+premain(String agentArgs);
+
+
+
+
+The agent class may also have an agentmain method for use when the agent is started
+after VM startup. When the agent is started using a command-line option, the agentmain
+method is not invoked.
+
+
+
+The agent class will be loaded by the system class loader
+(see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
+the class loader which typically loads the class containing the application main method.
+The premain methods will be run under the same security and classloader
+rules as the application main method.
+There are no modeling restrictions on what the agent premain method may do.
+Anything application main can do, including creating threads, is legal from premain.
+
+
+Each agent is passed its agent options via the agentArgs parameter.
+The agent options are passed as a single string,
+any additional parsing should be performed by the agent itself.
+
+
+If the agent cannot be resolved
+(for example, because the agent class cannot be loaded,
+or because the agent class does not have an appropriate premain method), the JVM will abort.
+If a premain method throws an uncaught exception, the JVM will abort.
+
+
+
+
+An implementation may provide a mechanism to start agents sometime after the
+the VM has started. The details as to how this is initiated are implementation
+specific but typically the application has already started and its
+main method has already been invoked. In cases where an implementation
+supports the starting of agents after the VM has started the following applies:
+
+
The manifest of the agent JAR must contain the attribute Agent-Class.
+ The value of this attribute is the name of the agent class.
The agent class must implement a public static agentmain method.
The system class loader ( + {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must + support a mechanism to add an agent JAR file to the system class path.
+The agent JAR is appended to the system class path. This is the class loader that typically loads
+the class containing the application main method. The agent class is loaded and the
+JVM attempts to invoke the agentmain method. The JVM first attempts to invoke
+the following method on the agent class:
+
+
+public static void
+agentmain(String agentArgs, Instrumentation inst);
+
+
+
++If the agent class does not implement this method then the JVM will attempt to invoke: + +
+public static void
+agentmain(String agentArgs);
+
+
+
+
+The agent class may also have an premain method for use when the agent is started
+using a command-line option. When the agent is started after VM startup the premain
+method is not invoked.
+
+
+
+The agent is passed its agent options via the agentArgs parameter.
+The agent options are passed as a single string,
+any additional parsing should be performed by the agent itself.
+
+
+The agentmain method should do any necessary initialization
+required to start the agent. When startup is complete the method should
+return. If the agent cannot be started
+(for example, because the agent class cannot be loaded,
+or because the agent class does not have a conformant agentmain method), the JVM will
+not abort. If the agentmain method throws an uncaught exception it will be ignored.
+
+
+
+
++ ++
+- +
Premain-Class- + When an agent is specified at JVM launch time this attribute + specifies the agent class. + That is, the class containing the
+ +premainmethod. + When an agent is specified at JVM launch time this attribute + is required. If the attribute is not present the JVM will abort. + Note: this is a class name, not a file name or path. +- +
Agent-Class- + If an implementation supports a mechanism to start agents + sometime after the VM has started then this attribute specifies + the agent class. + That is, the class containing the
+ +agentmainmethod. + This attribute is required, if it is not present the agent + will not be started. + Note: this is a class name, not a file name or path. +- +
Boot-Class-Path- + A list of paths to be searched by the bootstrap class + loader. Paths represent directories or libraries + (commonly referred to as JAR or zip libraries on + many platforms). + These paths are searched by the + bootstrap class loader after the platform specific + mechanisms of locating a class have failed. + Paths are searched in the order listed. + Paths in the list are separated by one or more spaces. + A path takes the syntax of the path component of a + hierarchical URI. The path is + absolute if it begins with a slash character ('/'), + otherwise it is relative. A relative path is resolved + against the absolute path of the agent JAR file. + Malformed and non-existent paths are ignored. + When an agent is started sometime after the VM has + started then paths that do not represent a JAR file + are ignored. + This attribute is optional. +
+- +
Can-Redefine-Classes- + Boolean (
+trueorfalse, case irrelevant). + Is the ability to redefine classes + needed by this agent. + Values other thantrueare consideredfalse. + This attribute is optional, the default isfalse. +- +
Can-Retransform-Classes- + Boolean (
+trueorfalse, case irrelevant). + Is the ability to retransform classes + needed by this agent. + Values other thantrueare consideredfalse. + This attribute is optional, the default isfalse. +- +
Can-Set-Native-Method-Prefix- + Boolean (
+trueorfalse, case irrelevant). + Is the ability to set native method prefix needed by this agent. + Values other thantrueare consideredfalse. + This attribute is optional, the default isfalse. +
+An agent JAR file may have both the Premain-Class and Agent-Class
+attributes present in the manifest. When the agent is started on the command-line using
+the -javaagent option then the Premain-Class attribute
+specifies the name of the agent class and the Agent-Class attribute is
+ignored. Similarly, if the agent is started sometime after the VM has started, then
+the Agent-Class attribute specifies the name of the agent class
+(the value of Premain-Class attribute is ignored).
+
+
+ +
+A platform MXBean is a managed bean that +conforms to the JMX +Instrumentation Specification and only uses a set of basic data types. +Each platform MXBean is a {@link java.lang.management.PlatformManagedObject} +with a unique +{@linkplain java.lang.management.PlatformManagedObject#getObjectName name}. +
+
The {@link java.lang.management.ManagementFactory} class is the management +factory class for the Java platform. This class provides a set of +static factory methods to obtain the MXBeans for the Java platform +to allow an application to access the MXBeans directly. + +
A platform MBeanServer can be accessed with the +{@link java.lang.management.ManagementFactory#getPlatformMBeanServer + getPlatformMBeanServer} method. On the first call to this method, +it creates the platform MBeanServer and registers all platform MXBeans +including {@linkplain java.lang.management.PlatformManagedObject +platform MXBeans}. +Each platform MXBean is registered with a unique name defined in +the specification of the management interface. +This is a single MBeanServer that can be shared by different managed +components running within the same Java virtual machine. + +
A management application and a platform MBeanServer of a running +virtual machine can interoperate +without requiring classes used by the platform MXBean interfaces. +The data types being transmitted between the JMX connector +server and the connector client are JMX +{@linkplain javax.management.openmbean.OpenType open types} and +this allows interoperation across versions. +A data type used by the MXBean interfaces are mapped to an +open type when being accessed via MBeanServer interface. +See the +MXBean specification for details. + +
An application can monitor the instrumentation of the +Java virtual machine and the runtime in the following ways: +
+1. Direct access to an MXBean interface +
+
+ RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean(); + + // Get the standard attribute "VmVendor" + String vendor = mxbean.getVmVendor(); ++
Or by calling the + {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class) + getPlatformMXBean} or + {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class) + getPlatformMXBeans} method: +
+ RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class); + + // Get the standard attribute "VmVendor" + String vendor = mxbean.getVmVendor(); ++
+
+ MBeanServerConnection mbs;
+
+ // Connect to a running JVM (or itself) and get MBeanServerConnection
+ // that has the JVM MBeans registered in it
+ ...
+
+ // Get a MBean proxy for RuntimeMXBean interface
+ RuntimeMXBean proxy =
+ {@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class)
+ ManagementFactory.getPlatformMXBean}(mbs,
+ RuntimeMXBean.class);
+ // Get standard attribute "VmVendor"
+ String vendor = proxy.getVmVendor();
+
+A proxy is typically used to access an MXBean + in a remote Java virtual machine. + An alternative way to create an MXBean proxy is: +
+ RuntimeMXBean proxy =
+ {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
+ ManagementFactory.newPlatformMXBeanProxy}(mbs,
+ ManagementFactory.RUNTIME_MXBEAN_NAME,
+ RuntimeMXBean.class);
+
++2. Indirect access to an MXBean interface via MBeanServer
+
+
+ MBeanServerConnection mbs;
+
+ // Connect to a running JVM (or itself) and get MBeanServerConnection
+ // that has the JVM MXBeans registered in it
+ ...
+
+ try {
+ // Assuming the RuntimeMXBean has been registered in mbs
+ ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
+
+ // Get standard attribute "VmVendor"
+ String vendor = (String) mbs.getAttribute(oname, "VmVendor");
+ } catch (....) {
+ // Catch the exceptions thrown by ObjectName constructor
+ // and MBeanServer.getAttribute method
+ ...
+ }
+
+A Java virtual machine implementation may add its platform extension to +the management interface by defining platform-dependent +interfaces that extend the standard management interfaces to include +platform-specific metrics and management operations. +The static factory methods in the ManagementFactory class will +return the MXBeans with the platform extension. + +
+It is recommended to name the platform-specific attributes with +a vendor-specific prefix such as the vendor's name to +avoid collisions of the attribute name between the future extension +to the standard management interface and the platform extension. +If the future extension to the standard management interface defines +a new attribute for a management interface and the attribute name +is happened to be same as some vendor-specific attribute's name, +the applications accessing that vendor-specific attribute would have +to be modified to cope with versioning and compatibility issues. + +
Below is an example showing how to access an attribute +from the platform extension: + +
+1) Direct access to the Oracle-specific MXBean interface +
+
+ List<com.sun.management.GarbageCollectorMXBean> mxbeans =
+ ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class);
+
+ for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
+ // Get the standard attribute "CollectionCount"
+ String count = mxbean.getCollectionCount();
+
+ // Get the platform-specific attribute "LastGcInfo"
+ GcInfo gcinfo = gc.getLastGcInfo();
+ ...
+ }
+
+
+
++2) Access the Oracle-specific MXBean interface via MBeanServer + through proxy + +
+ MBeanServerConnection mbs;
+
+ // Connect to a running JVM (or itself) and get MBeanServerConnection
+ // that has the JVM MXBeans registered in it
+ ...
+
+ List<com.sun.management.GarbageCollectorMXBean> mxbeans =
+ ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class);
+
+ for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
+ // Get the standard attribute "CollectionCount"
+ String count = mxbean.getCollectionCount();
+
+ // Get the platform-specific attribute "LastGcInfo"
+ GcInfo gcinfo = gc.getLastGcInfo();
+ ...
+ }
+Unless otherwise noted, passing a null argument to a constructor +or method in any class or interface in this package will cause a {@link +java.lang.NullPointerException NullPointerException} to be thrown. + +
The java.lang.management API is thread-safe. + +@see + JMX Specification. + +@author Mandy Chung +@since 1.5 + + + diff --git a/out/production/classes1/lang/ref/package.html b/out/production/classes1/lang/ref/package.html new file mode 100644 index 0000000000000000000000000000000000000000..f22a455f6ac6d614f156fe9cbc7b2307c78d68c0 --- /dev/null +++ b/out/production/classes1/lang/ref/package.html @@ -0,0 +1,147 @@ + + + + +
+ + +Provides reference-object classes, which support a limited degree of +interaction with the garbage collector. A program may use a reference object +to maintain a reference to some other object in such a way that the latter +object may still be reclaimed by the collector. A program may also arrange to +be notified some time after the collector has determined that the reachability +of a given object has changed. + + + Each reference-object type is implemented by a subclass of the abstract
+base {@link java.lang.ref.Reference} class. An instance of one of
+these subclasses encapsulates a single reference to a particular object, called
+the referent. Every reference object provides methods for getting and
+clearing the reference. Aside from the clearing operation reference objects
+are otherwise immutable, so no set operation is provided. A
+program may further subclass these subclasses, adding whatever fields and
+methods are required for its purposes, or it may use these subclasses without
+change.
+
+
+
{@link java.lang.ref.ReferenceQueue}
+class.
+
+The relationship between a registered reference object and its queue is +one-sided. That is, a queue does not keep track of the references that are +registered with it. If a registered reference becomes unreachable itself, then +it will never be enqueued. It is the responsibility of the program using +reference objects to ensure that the objects remain reachable for as long as +the program is interested in their referents. + +
While some programs will choose to dedicate a thread to removing reference
+objects from one or more queues and processing them, this is by no means
+necessary. A tactic that often works well is to examine a reference queue in
+the course of performing some other fairly-frequent action. For example, a
+hashtable that uses weak references to implement weak keys could poll its
+reference queue each time the table is accessed. This is how the {@link
+java.util.WeakHashMap} class works. Because the {@link
+java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll} method simply
+checks an internal data structure, this check will add little overhead to the
+hashtable access methods.
+
+
+
There are a few standard system properties used to +alter the mechanisms and behavior of the various classes of the +java.net package. Some are checked only once at startup of the VM, +and therefore are best set using the -D option of the java command, +while others have a more dynamic nature and can also be changed using +the System.setProperty() API. The purpose of this document is to list +and detail all of these properties.
+If there is no special note, a property value is checked every time it is used.
+ +java.net.preferIPv4Stack (default: false)
+ If IPv6 is available on the operating system the
+ underlying native socket will be, by default, an IPv6 socket which
+ lets applications connect to, and accept connections from, both
+ IPv4 and IPv6 hosts. However, in the case an application would
+ rather use IPv4 only sockets, then this property can be set to true.
+ The implication is that it will not be possible for the application
+ to communicate with IPv6 only hosts.
java.net.preferIPv6Addresses (default: false)
+ When dealing with a host which has both IPv4
+ and IPv6 addresses, and if IPv6 is available on the operating
+ system, the default behavior is to prefer using IPv4 addresses over
+ IPv6 ones. This is to ensure backward compatibility, for example
+ applications that depend on the representation of an IPv4 address
+ (e.g. 192.168.1.1). This property can be set to true to
+ change that preference and use IPv6 addresses over IPv4 ones where
+ possible.
Both of these properties are checked only once, at startup.
+ +A proxy server allows indirect connection to network services and +is used mainly for security (to get through firewalls) and +performance reasons (proxies often do provide caching mechanisms). +The following properties allow for configuration of the various type +of proxies.
+HTTP
+The following proxy settings are used by the HTTP protocol handler.
+http.proxyHost (default: <none>)
+ The hostname, or address, of the proxy server
+
http.proxyPort (default: 80)
+ The port number of the proxy server.
http.nonProxyHosts (default: localhost|127.*|[::1])
+ Indicates the hosts that should be accessed without going
+ through the proxy. Typically this defines internal hosts.
+ The value of this property is a list of hosts,
+ separated by the '|' character. In addition the wildcard
+ character '*' can be used for pattern matching. For example
+ -Dhttp.nonProxyHosts=”*.foo.com|localhost”
+ will indicate that every hosts in the foo.com domain and the
+ localhost should be accessed directly even if a proxy server is
+ specified.
The default value excludes all common variations of the loopback address.
+HTTPS
This is HTTP over SSL, a secure version of HTTP
+ mainly used when confidentiality (like on payment sites) is needed.
The following proxy settings are used by the HTTPS protocol handler.
+https.proxyHost(default: <none>)
+ The hostname, or address, of the proxy server
+
https.proxyPort (default: 443)
+ The port number of the proxy server.
The HTTPS protocol handler will use the same nonProxyHosts + property as the HTTP protocol.
+FTP
+The following proxy settings are used by the FTP protocol handler.
+ftp.proxyHost(default: <none>)
+ The hostname, or address, of the proxy server
+
ftp.proxyPort (default: 80)
+ The port number of the proxy server.
ftp.nonProxyHosts (default: localhost|127.*|[::1])
+ Indicates the hosts that should be accessed without going
+ through the proxy. Typically this defines internal hosts.
+ The value of this property is a list of hosts, separated by
+ the '|' character. In addition the wildcard character
+ '*' can be used for pattern matching. For example
+ -Dhttp.nonProxyHosts=”*.foo.com|localhost”
+ will indicate that every hosts in the foo.com domain and the
+ localhost should be accessed directly even if a proxy server is
+ specified.
The default value excludes all common variations of the loopback address.
+SOCKS
This is another type of proxy. It allows for lower
+ level type of tunneling since it works at the TCP level. In effect,
+ in the Java(tm) platform setting a SOCKS proxy server will result in
+ all TCP connections to go through that proxy, unless other proxies
+ are specified. If SOCKS is supported by a Java SE implementation, the
+ following properties will be used:
socksProxyHost (default: <none>)
+ The hostname, or address, of the proxy server.
socksProxyPort (default: 1080)
+ The port number of the proxy server.
socksProxyVersion (default: 5)
+ The version of the SOCKS protocol supported by the server. The
+ default is 5 indicating SOCKS V5, alternatively
+ 4 can be specified for SOCKS V4. Setting the property
+ to values other than these leads to unspecified behavior.
java.net.socks.username (default: <none>)
+ Username to use if the SOCKSv5 server asks for authentication
+ and no java.net.Authenticator instance was found.
java.net.socks.password (default: <none>)
+ Password to use if the SOCKSv5 server asks for authentication
+ and no java.net.Authenticator instance was found.
Note that if no authentication is provided with either the above + properties or an Authenticator, and the proxy requires one, then + the user.name property will be used with no password.
+java.net.useSystemProxies (default: false)
+ On recent Windows systems and on Gnome 2.x systems it is possible to
+ tell the java.net stack, setting this property to true, to use
+ the system proxy settings (both these systems let you set proxies
+ globally through their user interface). Note that this property is
+ checked only once at startup.
http.agent (default: “Java/<version>”)
+ Defines the string sent in the User-Agent request header in http
+ requests. Note that the string “Java/<version>” will
+ be appended to the one provided in the property (e.g. if
+ -Dhttp.agent=”foobar” is used, the User-Agent header will
+ contain “foobar Java/1.5.0” if the version of the VM is
+ 1.5.0). This property is checked only once at startup.
http.keepalive (default: true)
+ Indicates if persistent connections should be supported. They improve
+ performance by allowing the underlying socket connection to be reused
+ for multiple http requests. If this is set to true then persistent
+ connections will be requested with HTTP 1.1 servers.
http.maxConnections (default: 5)
+ If HTTP keepalive is enabled (see above) this value determines the
+ maximum number of idle connections that will be simultaneously kept
+ alive, per destination.
http.maxRedirects (default: 20)
+ This integer value determines the maximum number, for a given request,
+ of HTTP redirects that will be automatically followed by the
+ protocol handler.
http.auth.digest.validateServer (default: false)
+http.auth.digest.validateProxy (default: false)
+http.auth.digest.cnonceRepeat (default: 5)
+These 3 properties modify the behavior of the HTTP digest + authentication mechanism. Digest authentication provides a limited + ability for the server to authenticate itself to the client (i.e. + By proving it knows the user's password). However not all HTTP + servers support this capability and by default it is turned off. The + first two properties can be set to true to enforce this check for + authentication with either an origin or proxy server, respectively.
+It is usually not necessary to change the third property. It + determines how many times a cnonce value is re-used. This can be + useful when the MD5-sess algorithm is being used. Increasing this + value reduces the computational overhead on both client and server + by reducing the amount of material that has to be hashed for each + HTTP request.
+http.auth.ntlm.domain (default: <none>)
+ NTLM is another authentication scheme. It uses the
+ java.net.Authenticator class to acquire usernames and passwords when
+ they are needed. However NTLM also needs the NT domain name. There are
+ 3 options for specifying that domain:
Do not specify it. In some environments the domain is + actually not required and the application does not have to specify + it.
+The domain name can be encoded within the username by + prefixing the domain name, followed by a back-slash '\' before the + username. With this method existing applications that use the + authenticator class do not need to be modified, as long as users + are made aware that this notation must be used.
+If a domain name is not specified as in method 2) and these + property is defined, then its value will be used a the domain + name.
+All these properties are checked only once at startup.
+ +The java.net package, when doing name resolution, uses an address +cache for both security and performance reasons. Any address +resolution attempt, be it forward (name to IP address) or reverse (IP +address to name), will have its result cached, whether it was +successful or not, so that subsequent identical requests will not +have to access the naming service. These properties allow for some +tuning on how the cache is operating.
+networkaddress.cache.ttl (default: see below)
+ Value is an integer corresponding to the number of seconds successful
+ name lookups will be kept in the cache. A value of -1, or any other
+ negative value for that matter, indicates a “cache forever”
+ policy, while a value of 0 (zero) means no caching. The default value
+ is -1 (forever) if a security manager is installed, and implementation
+ specific when no security manager is installed.
networkaddress.cache.negative.ttl (default: 10)
+ Value is an integer corresponding to the number of seconds an
+ unsuccessful name lookup will be kept in the cache. A value of -1,
+ or any negative value, means “cache forever”, while a
+ value of 0 (zero) means no caching.
Since these 2 properties are part of the security policy, they are +not set by either the -D option or the System.setProperty() API, +instead they are set as security properties.
+ + diff --git a/out/production/classes1/nio/ByteBufferAs-X-Buffer.java.template b/out/production/classes1/nio/ByteBufferAs-X-Buffer.java.template new file mode 100644 index 0000000000000000000000000000000000000000..bae622550ac2fafb74ece6ae98b23c69f44641c3 --- /dev/null +++ b/out/production/classes1/nio/ByteBufferAs-X-Buffer.java.template @@ -0,0 +1,225 @@ +/* + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +package java.nio; + + +class ByteBufferAs$Type$Buffer$RW$$BO$ // package-private + extends {#if[ro]?ByteBufferAs}$Type$Buffer{#if[ro]?$BO$} +{ + +#if[rw] + + protected final ByteBuffer bb; + protected final int offset; + +#end[rw] + + ByteBufferAs$Type$Buffer$RW$$BO$(ByteBuffer bb) { // package-private +#if[rw] + super(-1, 0, + bb.remaining() >> $LG_BYTES_PER_VALUE$, + bb.remaining() >> $LG_BYTES_PER_VALUE$); + this.bb = bb; + // enforce limit == capacity + int cap = this.capacity(); + this.limit(cap); + int pos = this.position(); + assert (pos <= cap); + offset = pos; +#else[rw] + super(bb); +#end[rw] + } + + ByteBufferAs$Type$Buffer$RW$$BO$(ByteBuffer bb, + int mark, int pos, int lim, int cap, + int off) + { +#if[rw] + super(mark, pos, lim, cap); + this.bb = bb; + offset = off; +#else[rw] + super(bb, mark, pos, lim, cap, off); +#end[rw] + } + + public $Type$Buffer slice() { + int pos = this.position(); + int lim = this.limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + int off = (pos << $LG_BYTES_PER_VALUE$) + offset; + assert (off >= 0); + return new ByteBufferAs$Type$Buffer$RW$$BO$(bb, -1, 0, rem, rem, off); + } + + public $Type$Buffer duplicate() { + return new ByteBufferAs$Type$Buffer$RW$$BO$(bb, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + offset); + } + + public $Type$Buffer asReadOnlyBuffer() { +#if[rw] + return new ByteBufferAs$Type$BufferR$BO$(bb, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + offset); +#else[rw] + return duplicate(); +#end[rw] + } + +#if[rw] + + protected int ix(int i) { + return (i << $LG_BYTES_PER_VALUE$) + offset; + } + + public $type$ get() { + return Bits.get$Type$$BO$(bb, ix(nextGetIndex())); + } + + public $type$ get(int i) { + return Bits.get$Type$$BO$(bb, ix(checkIndex(i))); + } + +#if[streamableType] + $type$ getUnchecked(int i) { + return Bits.get$Type$$BO$(bb, ix(i)); + } +#end[streamableType] + +#end[rw] + + public $Type$Buffer put($type$ x) { +#if[rw] + Bits.put$Type$$BO$(bb, ix(nextPutIndex()), x); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put(int i, $type$ x) { +#if[rw] + Bits.put$Type$$BO$(bb, ix(checkIndex(i)), x); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer compact() { +#if[rw] + int pos = position(); + int lim = limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + + ByteBuffer db = bb.duplicate(); + db.limit(ix(lim)); + db.position(ix(0)); + ByteBuffer sb = db.slice(); + sb.position(pos << $LG_BYTES_PER_VALUE$); + sb.compact(); + position(rem); + limit(capacity()); + discardMark(); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public boolean isDirect() { + return bb.isDirect(); + } + + public boolean isReadOnly() { + return {#if[rw]?false:true}; + } + +#if[char] + + public String toString(int start, int end) { + if ((end > limit()) || (start > end)) + throw new IndexOutOfBoundsException(); + try { + int len = end - start; + char[] ca = new char[len]; + CharBuffer cb = CharBuffer.wrap(ca); + CharBuffer db = this.duplicate(); + db.position(start); + db.limit(end); + cb.put(db); + return new String(ca); + } catch (StringIndexOutOfBoundsException x) { + throw new IndexOutOfBoundsException(); + } + } + + + // --- Methods to support CharSequence --- + + public CharBuffer subSequence(int start, int end) { + int pos = position(); + int lim = limit(); + assert (pos <= lim); + pos = (pos <= lim ? pos : lim); + int len = lim - pos; + + if ((start < 0) || (end > len) || (start > end)) + throw new IndexOutOfBoundsException(); + return new ByteBufferAsCharBuffer$RW$$BO$(bb, + -1, + pos + start, + pos + end, + capacity(), + offset); + } + +#end[char] + + + public ByteOrder order() { +#if[boB] + return ByteOrder.BIG_ENDIAN; +#end[boB] +#if[boL] + return ByteOrder.LITTLE_ENDIAN; +#end[boL] + } + +} diff --git a/out/production/classes1/nio/Direct-X-Buffer-bin.java.template b/out/production/classes1/nio/Direct-X-Buffer-bin.java.template new file mode 100644 index 0000000000000000000000000000000000000000..538bd5f02c6a9676aa233bbb059b5adac6e79c85 --- /dev/null +++ b/out/production/classes1/nio/Direct-X-Buffer-bin.java.template @@ -0,0 +1,124 @@ +/* + * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +class XXX { + +#begin + +#if[rw] + + private $type$ get$Type$(long a) { + if (unaligned) { + $memtype$ x = unsafe.get$Memtype$(a); + return $fromBits$(nativeByteOrder ? x : Bits.swap(x)); + } + return Bits.get$Type$(a, bigEndian); + } + + public $type$ get$Type$() { + return get$Type$(ix(nextGetIndex($BYTES_PER_VALUE$))); + } + + public $type$ get$Type$(int i) { + return get$Type$(ix(checkIndex(i, $BYTES_PER_VALUE$))); + } + +#end[rw] + + private ByteBuffer put$Type$(long a, $type$ x) { +#if[rw] + if (unaligned) { + $memtype$ y = $toBits$(x); + unsafe.put$Memtype$(a, (nativeByteOrder ? y : Bits.swap(y))); + } else { + Bits.put$Type$(a, x, bigEndian); + } + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public ByteBuffer put$Type$($type$ x) { +#if[rw] + put$Type$(ix(nextPutIndex($BYTES_PER_VALUE$)), x); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public ByteBuffer put$Type$(int i, $type$ x) { +#if[rw] + put$Type$(ix(checkIndex(i, $BYTES_PER_VALUE$)), x); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer as$Type$Buffer() { + int off = this.position(); + int lim = this.limit(); + assert (off <= lim); + int rem = (off <= lim ? lim - off : 0); + + int size = rem >> $LG_BYTES_PER_VALUE$; + if (!unaligned && ((address + off) % $BYTES_PER_VALUE$ != 0)) { + return (bigEndian + ? ($Type$Buffer)(new ByteBufferAs$Type$Buffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : ($Type$Buffer)(new ByteBufferAs$Type$Buffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } else { + return (nativeByteOrder + ? ($Type$Buffer)(new Direct$Type$Buffer$RW$U(this, + -1, + 0, + size, + size, + off)) + : ($Type$Buffer)(new Direct$Type$Buffer$RW$S(this, + -1, + 0, + size, + size, + off))); + } + } + +#end + +} diff --git a/out/production/classes1/nio/Direct-X-Buffer.java.template b/out/production/classes1/nio/Direct-X-Buffer.java.template new file mode 100644 index 0000000000000000000000000000000000000000..57801f7c5c21355d79c48861a1a846b18483e82e --- /dev/null +++ b/out/production/classes1/nio/Direct-X-Buffer.java.template @@ -0,0 +1,490 @@ +/* + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +package java.nio; + +import java.io.FileDescriptor; +import sun.misc.Cleaner; +import sun.misc.Unsafe; +import sun.misc.VM; +import sun.nio.ch.DirectBuffer; + + +class Direct$Type$Buffer$RW$$BO$ +#if[rw] + extends {#if[byte]?Mapped$Type$Buffer:$Type$Buffer} +#else[rw] + extends Direct$Type$Buffer$BO$ +#end[rw] + implements DirectBuffer +{ + +#if[rw] + + // Cached unsafe-access object + protected static final Unsafe unsafe = Bits.unsafe(); + + // Cached array base offset + private static final long arrayBaseOffset = (long)unsafe.arrayBaseOffset($type$[].class); + + // Cached unaligned-access capability + protected static final boolean unaligned = Bits.unaligned(); + + // Base address, used in all indexing calculations + // NOTE: moved up to Buffer.java for speed in JNI GetDirectBufferAddress + // protected long address; + + // An object attached to this buffer. If this buffer is a view of another + // buffer then we use this field to keep a reference to that buffer to + // ensure that its memory isn't freed before we are done with it. + private final Object att; + + public Object attachment() { + return att; + } + +#if[byte] + + private static class Deallocator + implements Runnable + { + + private static Unsafe unsafe = Unsafe.getUnsafe(); + + private long address; + private long size; + private int capacity; + + private Deallocator(long address, long size, int capacity) { + assert (address != 0); + this.address = address; + this.size = size; + this.capacity = capacity; + } + + public void run() { + if (address == 0) { + // Paranoia + return; + } + unsafe.freeMemory(address); + address = 0; + Bits.unreserveMemory(size, capacity); + } + + } + + private final Cleaner cleaner; + + public Cleaner cleaner() { return cleaner; } + +#else[byte] + + public Cleaner cleaner() { return null; } + +#end[byte] + +#end[rw] + +#if[byte] + + // Primary constructor + // + Direct$Type$Buffer$RW$(int cap) { // package-private +#if[rw] + super(-1, 0, cap, cap); + boolean pa = VM.isDirectMemoryPageAligned(); + int ps = Bits.pageSize(); + long size = Math.max(1L, (long)cap + (pa ? ps : 0)); + Bits.reserveMemory(size, cap); + + long base = 0; + try { + base = unsafe.allocateMemory(size); + } catch (OutOfMemoryError x) { + Bits.unreserveMemory(size, cap); + throw x; + } + unsafe.setMemory(base, size, (byte) 0); + if (pa && (base % ps != 0)) { + // Round up to page boundary + address = base + ps - (base & (ps - 1)); + } else { + address = base; + } + cleaner = Cleaner.create(this, new Deallocator(base, size, cap)); + att = null; +#else[rw] + super(cap); +#end[rw] + } + +#if[rw] + + // Invoked to construct a direct ByteBuffer referring to the block of + // memory. A given arbitrary object may also be attached to the buffer. + // + Direct$Type$Buffer(long addr, int cap, Object ob) { + super(-1, 0, cap, cap); + address = addr; + cleaner = null; + att = ob; + } + + + // Invoked only by JNI: NewDirectByteBuffer(void*, long) + // + private Direct$Type$Buffer(long addr, int cap) { + super(-1, 0, cap, cap); + address = addr; + cleaner = null; + att = null; + } + +#end[rw] + + // For memory-mapped buffers -- invoked by FileChannelImpl via reflection + // + protected Direct$Type$Buffer$RW$(int cap, long addr, + FileDescriptor fd, + Runnable unmapper) + { +#if[rw] + super(-1, 0, cap, cap, fd); + address = addr; + cleaner = Cleaner.create(this, unmapper); + att = null; +#else[rw] + super(cap, addr, fd, unmapper); +#end[rw] + } + +#end[byte] + + // For duplicates and slices + // + Direct$Type$Buffer$RW$$BO$(DirectBuffer db, // package-private + int mark, int pos, int lim, int cap, + int off) + { +#if[rw] + super(mark, pos, lim, cap); + address = db.address() + off; +#if[byte] + cleaner = null; +#end[byte] + att = db; +#else[rw] + super(db, mark, pos, lim, cap, off); +#end[rw] + } + + public $Type$Buffer slice() { + int pos = this.position(); + int lim = this.limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + int off = (pos << $LG_BYTES_PER_VALUE$); + assert (off >= 0); + return new Direct$Type$Buffer$RW$$BO$(this, -1, 0, rem, rem, off); + } + + public $Type$Buffer duplicate() { + return new Direct$Type$Buffer$RW$$BO$(this, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + 0); + } + + public $Type$Buffer asReadOnlyBuffer() { +#if[rw] + return new Direct$Type$BufferR$BO$(this, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + 0); +#else[rw] + return duplicate(); +#end[rw] + } + +#if[rw] + + public long address() { + return address; + } + + private long ix(int i) { + return address + (i << $LG_BYTES_PER_VALUE$); + } + + public $type$ get() { + return $fromBits$($swap$(unsafe.get$Swaptype$(ix(nextGetIndex())))); + } + + public $type$ get(int i) { + return $fromBits$($swap$(unsafe.get$Swaptype$(ix(checkIndex(i))))); + } + +#if[streamableType] + $type$ getUnchecked(int i) { + return $fromBits$($swap$(unsafe.get$Swaptype$(ix(i)))); + } +#end[streamableType] + + public $Type$Buffer get($type$[] dst, int offset, int length) { +#if[rw] + if ((length << $LG_BYTES_PER_VALUE$) > Bits.JNI_COPY_TO_ARRAY_THRESHOLD) { + checkBounds(offset, length, dst.length); + int pos = position(); + int lim = limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + if (length > rem) + throw new BufferUnderflowException(); + +#if[!byte] + if (order() != ByteOrder.nativeOrder()) + Bits.copyTo$Memtype$Array(ix(pos), dst, + offset << $LG_BYTES_PER_VALUE$, + length << $LG_BYTES_PER_VALUE$); + else +#end[!byte] + Bits.copyToArray(ix(pos), dst, arrayBaseOffset, + offset << $LG_BYTES_PER_VALUE$, + length << $LG_BYTES_PER_VALUE$); + position(pos + length); + } else { + super.get(dst, offset, length); + } + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + +#end[rw] + + public $Type$Buffer put($type$ x) { +#if[rw] + unsafe.put$Swaptype$(ix(nextPutIndex()), $swap$($toBits$(x))); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put(int i, $type$ x) { +#if[rw] + unsafe.put$Swaptype$(ix(checkIndex(i)), $swap$($toBits$(x))); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put($Type$Buffer src) { +#if[rw] + if (src instanceof Direct$Type$Buffer$BO$) { + if (src == this) + throw new IllegalArgumentException(); + Direct$Type$Buffer$RW$$BO$ sb = (Direct$Type$Buffer$RW$$BO$)src; + + int spos = sb.position(); + int slim = sb.limit(); + assert (spos <= slim); + int srem = (spos <= slim ? slim - spos : 0); + + int pos = position(); + int lim = limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + + if (srem > rem) + throw new BufferOverflowException(); + unsafe.copyMemory(sb.ix(spos), ix(pos), srem << $LG_BYTES_PER_VALUE$); + sb.position(spos + srem); + position(pos + srem); + } else if (src.hb != null) { + + int spos = src.position(); + int slim = src.limit(); + assert (spos <= slim); + int srem = (spos <= slim ? slim - spos : 0); + + put(src.hb, src.offset + spos, srem); + src.position(spos + srem); + + } else { + super.put(src); + } + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put($type$[] src, int offset, int length) { +#if[rw] + if ((length << $LG_BYTES_PER_VALUE$) > Bits.JNI_COPY_FROM_ARRAY_THRESHOLD) { + checkBounds(offset, length, src.length); + int pos = position(); + int lim = limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + if (length > rem) + throw new BufferOverflowException(); + +#if[!byte] + if (order() != ByteOrder.nativeOrder()) + Bits.copyFrom$Memtype$Array(src, offset << $LG_BYTES_PER_VALUE$, + ix(pos), length << $LG_BYTES_PER_VALUE$); + else +#end[!byte] + Bits.copyFromArray(src, arrayBaseOffset, offset << $LG_BYTES_PER_VALUE$, + ix(pos), length << $LG_BYTES_PER_VALUE$); + position(pos + length); + } else { + super.put(src, offset, length); + } + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer compact() { +#if[rw] + int pos = position(); + int lim = limit(); + assert (pos <= lim); + int rem = (pos <= lim ? lim - pos : 0); + + unsafe.copyMemory(ix(pos), ix(0), rem << $LG_BYTES_PER_VALUE$); + position(rem); + limit(capacity()); + discardMark(); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public boolean isDirect() { + return true; + } + + public boolean isReadOnly() { + return {#if[rw]?false:true}; + } + + +#if[char] + + public String toString(int start, int end) { + if ((end > limit()) || (start > end)) + throw new IndexOutOfBoundsException(); + try { + int len = end - start; + char[] ca = new char[len]; + CharBuffer cb = CharBuffer.wrap(ca); + CharBuffer db = this.duplicate(); + db.position(start); + db.limit(end); + cb.put(db); + return new String(ca); + } catch (StringIndexOutOfBoundsException x) { + throw new IndexOutOfBoundsException(); + } + } + + + // --- Methods to support CharSequence --- + + public CharBuffer subSequence(int start, int end) { + int pos = position(); + int lim = limit(); + assert (pos <= lim); + pos = (pos <= lim ? pos : lim); + int len = lim - pos; + + if ((start < 0) || (end > len) || (start > end)) + throw new IndexOutOfBoundsException(); + return new DirectCharBuffer$RW$$BO$(this, + -1, + pos + start, + pos + end, + capacity(), + offset); + } + +#end[char] + + + +#if[!byte] + + public ByteOrder order() { +#if[boS] + return ((ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN) + ? ByteOrder.LITTLE_ENDIAN : ByteOrder.BIG_ENDIAN); +#end[boS] +#if[boU] + return ((ByteOrder.nativeOrder() != ByteOrder.BIG_ENDIAN) + ? ByteOrder.LITTLE_ENDIAN : ByteOrder.BIG_ENDIAN); +#end[boU] + } + +#end[!byte] + + + +#if[byte] + + byte _get(int i) { // package-private + return unsafe.getByte(address + i); + } + + void _put(int i, byte b) { // package-private +#if[rw] + unsafe.putByte(address + i, b); +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + // #BIN + // + // Binary-data access methods for short, char, int, long, float, + // and double will be inserted here + +#end[byte] + +} diff --git a/out/production/classes1/nio/Heap-X-Buffer.java.template b/out/production/classes1/nio/Heap-X-Buffer.java.template new file mode 100644 index 0000000000000000000000000000000000000000..e8639c4d21fbabc182fed26c91682f5392e1ea71 --- /dev/null +++ b/out/production/classes1/nio/Heap-X-Buffer.java.template @@ -0,0 +1,601 @@ +/* + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +package java.nio; + + +/** +#if[rw] + * A read/write Heap$Type$Buffer. +#else[rw] + * A read-only Heap$Type$Buffer. This class extends the corresponding + * read/write class, overriding the mutation methods to throw a {@link + * ReadOnlyBufferException} and overriding the view-buffer methods to return an + * instance of this class rather than of the superclass. +#end[rw] + */ + +class Heap$Type$Buffer$RW$ + extends {#if[ro]?Heap}$Type$Buffer +{ + + // For speed these fields are actually declared in X-Buffer; + // these declarations are here as documentation + /* +#if[rw] + protected final $type$[] hb; + protected final int offset; +#end[rw] + */ + + Heap$Type$Buffer$RW$(int cap, int lim) { // package-private +#if[rw] + super(-1, 0, lim, cap, new $type$[cap], 0); + /* + hb = new $type$[cap]; + offset = 0; + */ +#else[rw] + super(cap, lim); + this.isReadOnly = true; +#end[rw] + } + + Heap$Type$Buffer$RW$($type$[] buf, int off, int len) { // package-private +#if[rw] + super(-1, off, off + len, buf.length, buf, 0); + /* + hb = buf; + offset = 0; + */ +#else[rw] + super(buf, off, len); + this.isReadOnly = true; +#end[rw] + } + + protected Heap$Type$Buffer$RW$($type$[] buf, + int mark, int pos, int lim, int cap, + int off) + { +#if[rw] + super(mark, pos, lim, cap, buf, off); + /* + hb = buf; + offset = off; + */ +#else[rw] + super(buf, mark, pos, lim, cap, off); + this.isReadOnly = true; +#end[rw] + } + + public $Type$Buffer slice() { + return new Heap$Type$Buffer$RW$(hb, + -1, + 0, + this.remaining(), + this.remaining(), + this.position() + offset); + } + + public $Type$Buffer duplicate() { + return new Heap$Type$Buffer$RW$(hb, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + offset); + } + + public $Type$Buffer asReadOnlyBuffer() { +#if[rw] + return new Heap$Type$BufferR(hb, + this.markValue(), + this.position(), + this.limit(), + this.capacity(), + offset); +#else[rw] + return duplicate(); +#end[rw] + } + +#if[rw] + + protected int ix(int i) { + return i + offset; + } + + public $type$ get() { + return hb[ix(nextGetIndex())]; + } + + public $type$ get(int i) { + return hb[ix(checkIndex(i))]; + } + +#if[streamableType] + $type$ getUnchecked(int i) { + return hb[ix(i)]; + } +#end[streamableType] + + public $Type$Buffer get($type$[] dst, int offset, int length) { + checkBounds(offset, length, dst.length); + if (length > remaining()) + throw new BufferUnderflowException(); + System.arraycopy(hb, ix(position()), dst, offset, length); + position(position() + length); + return this; + } + + public boolean isDirect() { + return false; + } + +#end[rw] + + public boolean isReadOnly() { + return {#if[rw]?false:true}; + } + + public $Type$Buffer put($type$ x) { +#if[rw] + hb[ix(nextPutIndex())] = x; + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put(int i, $type$ x) { +#if[rw] + hb[ix(checkIndex(i))] = x; + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put($type$[] src, int offset, int length) { +#if[rw] + checkBounds(offset, length, src.length); + if (length > remaining()) + throw new BufferOverflowException(); + System.arraycopy(src, offset, hb, ix(position()), length); + position(position() + length); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer put($Type$Buffer src) { +#if[rw] + if (src instanceof Heap$Type$Buffer) { + if (src == this) + throw new IllegalArgumentException(); + Heap$Type$Buffer sb = (Heap$Type$Buffer)src; + int n = sb.remaining(); + if (n > remaining()) + throw new BufferOverflowException(); + System.arraycopy(sb.hb, sb.ix(sb.position()), + hb, ix(position()), n); + sb.position(sb.position() + n); + position(position() + n); + } else if (src.isDirect()) { + int n = src.remaining(); + if (n > remaining()) + throw new BufferOverflowException(); + src.get(hb, ix(position()), n); + position(position() + n); + } else { + super.put(src); + } + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer compact() { +#if[rw] + System.arraycopy(hb, ix(position()), hb, ix(0), remaining()); + position(remaining()); + limit(capacity()); + discardMark(); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + + +#if[byte] + + byte _get(int i) { // package-private + return hb[i]; + } + + void _put(int i, byte b) { // package-private +#if[rw] + hb[i] = b; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + // char + +#if[rw] + + public char getChar() { + return Bits.getChar(this, ix(nextGetIndex(2)), bigEndian); + } + + public char getChar(int i) { + return Bits.getChar(this, ix(checkIndex(i, 2)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putChar(char x) { +#if[rw] + Bits.putChar(this, ix(nextPutIndex(2)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putChar(int i, char x) { +#if[rw] + Bits.putChar(this, ix(checkIndex(i, 2)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public CharBuffer asCharBuffer() { + int size = this.remaining() >> 1; + int off = offset + position(); + return (bigEndian + ? (CharBuffer)(new ByteBufferAsCharBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (CharBuffer)(new ByteBufferAsCharBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + + // short + +#if[rw] + + public short getShort() { + return Bits.getShort(this, ix(nextGetIndex(2)), bigEndian); + } + + public short getShort(int i) { + return Bits.getShort(this, ix(checkIndex(i, 2)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putShort(short x) { +#if[rw] + Bits.putShort(this, ix(nextPutIndex(2)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putShort(int i, short x) { +#if[rw] + Bits.putShort(this, ix(checkIndex(i, 2)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public ShortBuffer asShortBuffer() { + int size = this.remaining() >> 1; + int off = offset + position(); + return (bigEndian + ? (ShortBuffer)(new ByteBufferAsShortBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (ShortBuffer)(new ByteBufferAsShortBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + + // int + +#if[rw] + + public int getInt() { + return Bits.getInt(this, ix(nextGetIndex(4)), bigEndian); + } + + public int getInt(int i) { + return Bits.getInt(this, ix(checkIndex(i, 4)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putInt(int x) { +#if[rw] + Bits.putInt(this, ix(nextPutIndex(4)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putInt(int i, int x) { +#if[rw] + Bits.putInt(this, ix(checkIndex(i, 4)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public IntBuffer asIntBuffer() { + int size = this.remaining() >> 2; + int off = offset + position(); + return (bigEndian + ? (IntBuffer)(new ByteBufferAsIntBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (IntBuffer)(new ByteBufferAsIntBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + + // long + +#if[rw] + + public long getLong() { + return Bits.getLong(this, ix(nextGetIndex(8)), bigEndian); + } + + public long getLong(int i) { + return Bits.getLong(this, ix(checkIndex(i, 8)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putLong(long x) { +#if[rw] + Bits.putLong(this, ix(nextPutIndex(8)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putLong(int i, long x) { +#if[rw] + Bits.putLong(this, ix(checkIndex(i, 8)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public LongBuffer asLongBuffer() { + int size = this.remaining() >> 3; + int off = offset + position(); + return (bigEndian + ? (LongBuffer)(new ByteBufferAsLongBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (LongBuffer)(new ByteBufferAsLongBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + + // float + +#if[rw] + + public float getFloat() { + return Bits.getFloat(this, ix(nextGetIndex(4)), bigEndian); + } + + public float getFloat(int i) { + return Bits.getFloat(this, ix(checkIndex(i, 4)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putFloat(float x) { +#if[rw] + Bits.putFloat(this, ix(nextPutIndex(4)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putFloat(int i, float x) { +#if[rw] + Bits.putFloat(this, ix(checkIndex(i, 4)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public FloatBuffer asFloatBuffer() { + int size = this.remaining() >> 2; + int off = offset + position(); + return (bigEndian + ? (FloatBuffer)(new ByteBufferAsFloatBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (FloatBuffer)(new ByteBufferAsFloatBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + + // double + +#if[rw] + + public double getDouble() { + return Bits.getDouble(this, ix(nextGetIndex(8)), bigEndian); + } + + public double getDouble(int i) { + return Bits.getDouble(this, ix(checkIndex(i, 8)), bigEndian); + } + +#end[rw] + + public $Type$Buffer putDouble(double x) { +#if[rw] + Bits.putDouble(this, ix(nextPutIndex(8)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public $Type$Buffer putDouble(int i, double x) { +#if[rw] + Bits.putDouble(this, ix(checkIndex(i, 8)), x, bigEndian); + return this; +#else[rw] + throw new ReadOnlyBufferException(); +#end[rw] + } + + public DoubleBuffer asDoubleBuffer() { + int size = this.remaining() >> 3; + int off = offset + position(); + return (bigEndian + ? (DoubleBuffer)(new ByteBufferAsDoubleBuffer$RW$B(this, + -1, + 0, + size, + size, + off)) + : (DoubleBuffer)(new ByteBufferAsDoubleBuffer$RW$L(this, + -1, + 0, + size, + size, + off))); + } + + +#end[byte] + + +#if[char] + + String toString(int start, int end) { // package-private + try { + return new String(hb, start + offset, end - start); + } catch (StringIndexOutOfBoundsException x) { + throw new IndexOutOfBoundsException(); + } + } + + + // --- Methods to support CharSequence --- + + public CharBuffer subSequence(int start, int end) { + if ((start < 0) + || (end > length()) + || (start > end)) + throw new IndexOutOfBoundsException(); + int pos = position(); + return new HeapCharBuffer$RW$(hb, + -1, + pos + start, + pos + end, + capacity(), + offset); + } + +#end[char] + + +#if[!byte] + + public ByteOrder order() { + return ByteOrder.nativeOrder(); + } + +#end[!byte] + +} diff --git a/out/production/classes1/nio/X-Buffer-bin.java.template b/out/production/classes1/nio/X-Buffer-bin.java.template new file mode 100644 index 0000000000000000000000000000000000000000..340a497541c2011f29e49654f7b9e30d4a4cc3de --- /dev/null +++ b/out/production/classes1/nio/X-Buffer-bin.java.template @@ -0,0 +1,132 @@ +/* + * Copyright (c) 2000, 2002, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +class XXX { + +#begin + + /** + * Relative get method for reading $a$ $type$ value. + * + *Reads the next $nbytes$ bytes at this buffer's current position, + * composing them into $a$ $type$ value according to the current byte order, + * and then increments the position by $nbytes$.
+ * + * @return The $type$ value at the buffer's current position + * + * @throws BufferUnderflowException + * If there are fewer than $nbytes$ bytes + * remaining in this buffer + */ + public abstract $type$ get$Type$(); + + /** + * Relative put method for writing $a$ $type$ + * value (optional operation). + * + *Writes $nbytes$ bytes containing the given $type$ value, in the + * current byte order, into this buffer at the current position, and then + * increments the position by $nbytes$.
+ * + * @param value + * The $type$ value to be written + * + * @return This buffer + * + * @throws BufferOverflowException + * If there are fewer than $nbytes$ bytes + * remaining in this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public abstract ByteBuffer put$Type$($type$ value); + + /** + * Absolute get method for reading $a$ $type$ value. + * + *Reads $nbytes$ bytes at the given index, composing them into a + * $type$ value according to the current byte order.
+ * + * @param index + * The index from which the bytes will be read + * + * @return The $type$ value at the given index + * + * @throws IndexOutOfBoundsException + * If index is negative + * or not smaller than the buffer's limit, + * minus $nbytesButOne$ + */ + public abstract $type$ get$Type$(int index); + + /** + * Absolute put method for writing $a$ $type$ + * value (optional operation). + * + *Writes $nbytes$ bytes containing the given $type$ value, in the + * current byte order, into this buffer at the given index.
+ * + * @param index + * The index at which the bytes will be written + * + * @param value + * The $type$ value to be written + * + * @return This buffer + * + * @throws IndexOutOfBoundsException + * If index is negative + * or not smaller than the buffer's limit, + * minus $nbytesButOne$ + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public abstract ByteBuffer put$Type$(int index, $type$ value); + + /** + * Creates a view of this byte buffer as $a$ $type$ buffer. + * + *The content of the new buffer will start at this buffer's current + * position. Changes to this buffer's content will be visible in the new + * buffer, and vice versa; the two buffers' position, limit, and mark + * values will be independent. + * + *
The new buffer's position will be zero, its capacity and its limit + * will be the number of bytes remaining in this buffer divided by + * $nbytes$, and its mark will be undefined. The new buffer will be direct + * if, and only if, this buffer is direct, and it will be read-only if, and + * only if, this buffer is read-only.
+ * + * @return A new $type$ buffer + */ + public abstract $Type$Buffer as$Type$Buffer(); + +#end + +} diff --git a/out/production/classes1/nio/X-Buffer.java.template b/out/production/classes1/nio/X-Buffer.java.template new file mode 100644 index 0000000000000000000000000000000000000000..af9eca1c7713cf8c1f82762226ad1130ca1f8113 --- /dev/null +++ b/out/production/classes1/nio/X-Buffer.java.template @@ -0,0 +1,1503 @@ +/* + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +package java.nio; + +#if[char] +import java.io.IOException; +#end[char] +#if[streamableType] +import java.util.Spliterator; +import java.util.stream.StreamSupport; +import java.util.stream.$Streamtype$Stream; +#end[streamableType] + +/** + * $A$ $type$ buffer. + * + *This class defines {#if[byte]?six:four} categories of operations upon + * $type$ buffers: + * + *
Absolute and relative {@link #get() get} and + * {@link #put($type$) put} methods that read and write + * single $type$s;
Relative {@link #get($type$[]) bulk get} + * methods that transfer contiguous sequences of $type$s from this buffer + * into an array; {#if[!byte]?and}
Relative {@link #put($type$[]) bulk put} + * methods that transfer contiguous sequences of $type$s from $a$ + * $type$ array{#if[char]?, a string,} or some other $type$ + * buffer into this buffer;{#if[!byte]? and}
Absolute and relative {@link #getChar() get} + * and {@link #putChar(char) put} methods that read and + * write values of other primitive types, translating them to and from + * sequences of bytes in a particular byte order;
Methods for creating view buffers, + * which allow a byte buffer to be viewed as a buffer containing values of + * some other primitive type; and
Methods for {@link #compact compacting}, {@link + * #duplicate duplicating}, and {@link #slice slicing} + * $a$ $type$ buffer.
$Type$ buffers can be created either by {@link #allocate + * allocation}, which allocates space for the buffer's + * +#if[byte] + * + * content, or by {@link #wrap($type$[]) wrapping} an + * existing $type$ array {#if[char]?or string} into a buffer. + * +#else[byte] + * + * content, by {@link #wrap($type$[]) wrapping} an existing + * $type$ array {#if[char]?or string} into a buffer, or by creating a + * view of an existing byte buffer. + * +#end[byte] + * +#if[byte] + * + * + *
A byte buffer is either direct or non-direct. Given a + * direct byte buffer, the Java virtual machine will make a best effort to + * perform native I/O operations directly upon it. That is, it will attempt to + * avoid copying the buffer's content to (or from) an intermediate buffer + * before (or after) each invocation of one of the underlying operating + * system's native I/O operations. + * + *
A direct byte buffer may be created by invoking the {@link + * #allocateDirect(int) allocateDirect} factory method of this class. The + * buffers returned by this method typically have somewhat higher allocation + * and deallocation costs than non-direct buffers. The contents of direct + * buffers may reside outside of the normal garbage-collected heap, and so + * their impact upon the memory footprint of an application might not be + * obvious. It is therefore recommended that direct buffers be allocated + * primarily for large, long-lived buffers that are subject to the underlying + * system's native I/O operations. In general it is best to allocate direct + * buffers only when they yield a measureable gain in program performance. + * + *
A direct byte buffer may also be created by {@link + * java.nio.channels.FileChannel#map mapping} a region of a file + * directly into memory. An implementation of the Java platform may optionally + * support the creation of direct byte buffers from native code via JNI. If an + * instance of one of these kinds of buffers refers to an inaccessible region + * of memory then an attempt to access that region will not change the buffer's + * content and will cause an unspecified exception to be thrown either at the + * time of the access or at some later time. + * + *
Whether a byte buffer is direct or non-direct may be determined by + * invoking its {@link #isDirect isDirect} method. This method is provided so + * that explicit buffer management can be done in performance-critical code. + * + * + * + *
This class defines methods for reading and writing values of all other + * primitive types, except boolean. Primitive values are translated + * to (or from) sequences of bytes according to the buffer's current byte + * order, which may be retrieved and modified via the {@link #order order} + * methods. Specific byte orders are represented by instances of the {@link + * ByteOrder} class. The initial order of a byte buffer is always {@link + * ByteOrder#BIG_ENDIAN BIG_ENDIAN}. + * + *
For access to heterogeneous binary data, that is, sequences of values of + * different types, this class defines a family of absolute and relative + * get and put methods for each type. For 32-bit floating-point + * values, for example, this class defines: + * + *
+ * float {@link #getFloat()}
+ * float {@link #getFloat(int) getFloat(int index)}
+ * void {@link #putFloat(float) putFloat(float f)}
+ * void {@link #putFloat(int,float) putFloat(int index, float f)}Corresponding methods are defined for the types char, + * short, int, long, and double. The index + * parameters of the absolute get and put methods are in terms of + * bytes rather than of the type being read or written. + * + * + * + *
For access to homogeneous binary data, that is, sequences of values of + * the same type, this class defines methods that can create views of a + * given byte buffer. A view buffer is simply another buffer whose + * content is backed by the byte buffer. Changes to the byte buffer's content + * will be visible in the view buffer, and vice versa; the two buffers' + * position, limit, and mark values are independent. The {@link + * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of + * the {@link FloatBuffer} class that is backed by the byte buffer upon which + * the method is invoked. Corresponding view-creation methods are defined for + * the types char, short, int, long, and + * double. + * + *
View buffers have three important advantages over the families of + * type-specific get and put methods described above: + * + *
A view buffer is indexed not in terms of bytes but rather in terms + * of the type-specific size of its values;
A view buffer provides relative bulk get and put + * methods that can transfer contiguous sequences of values between a buffer + * and an array or some other buffer of the same type; and
A view buffer is potentially much more efficient because it will + * be direct if, and only if, its backing byte buffer is direct.
The byte order of a view buffer is fixed to be that of its byte buffer + * at the time that the view is created.
+ * +#end[byte] +* +#if[!byte] + * + *Like a byte buffer, $a$ $type$ buffer is either direct or non-direct. A + * $type$ buffer created via the wrap methods of this class will + * be non-direct. $A$ $type$ buffer created as a view of a byte buffer will + * be direct if, and only if, the byte buffer itself is direct. Whether or not + * $a$ $type$ buffer is direct may be determined by invoking the {@link + * #isDirect isDirect} method.
+ * +#end[!byte] +* +#if[char] + * + *This class implements the {@link CharSequence} interface so that + * character buffers may be used wherever character sequences are accepted, for + * example in the regular-expression package {@link java.util.regex}. + *
+ * +#end[char] + * +#if[byte] + *Methods in this class that do not otherwise have a value to return are + * specified to return the buffer upon which they are invoked. This allows + * method invocations to be chained. + * +#if[byte] + * + * The sequence of statements + * + *
+ * + * can, for example, be replaced by the single statement + * + *+ * bb.putInt(0xCAFEBABE); + * bb.putShort(3); + * bb.putShort(45);
+ * +#end[byte] +#if[char] + * + * The sequence of statements + * + *+ * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);
+ * cb.put("text/");
+ * cb.put(subtype);
+ * cb.put("; charset=");
+ * cb.put(enc);
+ * cb.put("text/").put(subtype).put("; charset=").put(enc);The new buffer's position will be zero, its limit will be its + * capacity, its mark will be undefined, and each of its elements will be + * initialized to zero. Whether or not it has a + * {@link #hasArray backing array} is unspecified. + * + * @param capacity + * The new buffer's capacity, in $type$s + * + * @return The new $type$ buffer + * + * @throws IllegalArgumentException + * If the capacity is a negative integer + */ + public static $Type$Buffer allocateDirect(int capacity) { + return new Direct$Type$Buffer(capacity); + } + +#end[byte] + + /** + * Allocates a new $type$ buffer. + * + *
The new buffer's position will be zero, its limit will be its + * capacity, its mark will be undefined, and each of its elements will be + * initialized to zero. It will have a {@link #array backing array}, + * and its {@link #arrayOffset array offset} will be zero. + * + * @param capacity + * The new buffer's capacity, in $type$s + * + * @return The new $type$ buffer + * + * @throws IllegalArgumentException + * If the capacity is a negative integer + */ + public static $Type$Buffer allocate(int capacity) { + if (capacity < 0) + throw new IllegalArgumentException(); + return new Heap$Type$Buffer(capacity, capacity); + } + + /** + * Wraps $a$ $type$ array into a buffer. + * + *
The new buffer will be backed by the given $type$ array; + * that is, modifications to the buffer will cause the array to be modified + * and vice versa. The new buffer's capacity will be + * array.length, its position will be offset, its limit + * will be offset + length, and its mark will be undefined. Its + * {@link #array backing array} will be the given array, and + * its {@link #arrayOffset array offset} will be zero.
+ * + * @param array + * The array that will back the new buffer + * + * @param offset + * The offset of the subarray to be used; must be non-negative and + * no larger than array.length. The new buffer's position + * will be set to this value. + * + * @param length + * The length of the subarray to be used; + * must be non-negative and no larger than + * array.length - offset. + * The new buffer's limit will be set to offset + length. + * + * @return The new $type$ buffer + * + * @throws IndexOutOfBoundsException + * If the preconditions on the offset and length + * parameters do not hold + */ + public static $Type$Buffer wrap($type$[] array, + int offset, int length) + { + try { + return new Heap$Type$Buffer(array, offset, length); + } catch (IllegalArgumentException x) { + throw new IndexOutOfBoundsException(); + } + } + + /** + * Wraps $a$ $type$ array into a buffer. + * + *The new buffer will be backed by the given $type$ array; + * that is, modifications to the buffer will cause the array to be modified + * and vice versa. The new buffer's capacity and limit will be + * array.length, its position will be zero, and its mark will be + * undefined. Its {@link #array backing array} will be the + * given array, and its {@link #arrayOffset array offset>} will + * be zero.
+ * + * @param array + * The array that will back this buffer + * + * @return The new $type$ buffer + */ + public static $Type$Buffer wrap($type$[] array) { + return wrap(array, 0, array.length); + } + +#if[char] + + /** + * Attempts to read characters into the specified character buffer. + * The buffer is used as a repository of characters as-is: the only + * changes made are the results of a put operation. No flipping or + * rewinding of the buffer is performed. + * + * @param target the buffer to read characters into + * @return The number of characters added to the buffer, or + * -1 if this source of characters is at its end + * @throws IOException if an I/O error occurs + * @throws NullPointerException if target is null + * @throws ReadOnlyBufferException if target is a read only buffer + * @since 1.5 + */ + public int read(CharBuffer target) throws IOException { + // Determine the number of bytes n that can be transferred + int targetRemaining = target.remaining(); + int remaining = remaining(); + if (remaining == 0) + return -1; + int n = Math.min(remaining, targetRemaining); + int limit = limit(); + // Set source limit to prevent target overflow + if (targetRemaining < remaining) + limit(position() + n); + try { + if (n > 0) + target.put(this); + } finally { + limit(limit); // restore real limit + } + return n; + } + + /** + * Wraps a character sequence into a buffer. + * + *The content of the new, read-only buffer will be the content of the + * given character sequence. The buffer's capacity will be + * csq.length(), its position will be start, its limit + * will be end, and its mark will be undefined.
+ * + * @param csq + * The character sequence from which the new character buffer is to + * be created + * + * @param start + * The index of the first character to be used; + * must be non-negative and no larger than csq.length(). + * The new buffer's position will be set to this value. + * + * @param end + * The index of the character following the last character to be + * used; must be no smaller than start and no larger + * than csq.length(). + * The new buffer's limit will be set to this value. + * + * @return The new character buffer + * + * @throws IndexOutOfBoundsException + * If the preconditions on the start and end + * parameters do not hold + */ + public static CharBuffer wrap(CharSequence csq, int start, int end) { + try { + return new StringCharBuffer(csq, start, end); + } catch (IllegalArgumentException x) { + throw new IndexOutOfBoundsException(); + } + } + + /** + * Wraps a character sequence into a buffer. + * + *The content of the new, read-only buffer will be the content of the + * given character sequence. The new buffer's capacity and limit will be + * csq.length(), its position will be zero, and its mark will be + * undefined.
+ * + * @param csq + * The character sequence from which the new character buffer is to + * be created + * + * @return The new character buffer + */ + public static CharBuffer wrap(CharSequence csq) { + return wrap(csq, 0, csq.length()); + } + +#end[char] + + /** + * Creates a new $type$ buffer whose content is a shared subsequence of + * this buffer's content. + * + *The content of the new buffer will start at this buffer's current + * position. Changes to this buffer's content will be visible in the new + * buffer, and vice versa; the two buffers' position, limit, and mark + * values will be independent. + * + *
The new buffer's position will be zero, its capacity and its limit + * will be the number of $type$s remaining in this buffer, and its mark + * will be undefined. The new buffer will be direct if, and only if, this + * buffer is direct, and it will be read-only if, and only if, this buffer + * is read-only.
+ * + * @return The new $type$ buffer + */ + public abstract $Type$Buffer slice(); + + /** + * Creates a new $type$ buffer that shares this buffer's content. + * + *The content of the new buffer will be that of this buffer. Changes + * to this buffer's content will be visible in the new buffer, and vice + * versa; the two buffers' position, limit, and mark values will be + * independent. + * + *
The new buffer's capacity, limit, position, and mark values will be + * identical to those of this buffer. The new buffer will be direct if, + * and only if, this buffer is direct, and it will be read-only if, and + * only if, this buffer is read-only.
+ * + * @return The new $type$ buffer + */ + public abstract $Type$Buffer duplicate(); + + /** + * Creates a new, read-only $type$ buffer that shares this buffer's + * content. + * + *The content of the new buffer will be that of this buffer. Changes + * to this buffer's content will be visible in the new buffer; the new + * buffer itself, however, will be read-only and will not allow the shared + * content to be modified. The two buffers' position, limit, and mark + * values will be independent. + * + *
The new buffer's capacity, limit, position, and mark values will be + * identical to those of this buffer. + * + *
If this buffer is itself read-only then this method behaves in + * exactly the same way as the {@link #duplicate duplicate} method.
+ * + * @return The new, read-only $type$ buffer + */ + public abstract $Type$Buffer asReadOnlyBuffer(); + + + // -- Singleton get/put methods -- + + /** + * Relative get method. Reads the $type$ at this buffer's + * current position, and then increments the position. + * + * @return The $type$ at the buffer's current position + * + * @throws BufferUnderflowException + * If the buffer's current position is not smaller than its limit + */ + public abstract $type$ get(); + + /** + * Relative put method (optional operation). + * + *Writes the given $type$ into this buffer at the current + * position, and then increments the position.
+ * + * @param $x$ + * The $type$ to be written + * + * @return This buffer + * + * @throws BufferOverflowException + * If this buffer's current position is not smaller than its limit + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public abstract $Type$Buffer put($type$ $x$); + + /** + * Absolute get method. Reads the $type$ at the given + * index. + * + * @param index + * The index from which the $type$ will be read + * + * @return The $type$ at the given index + * + * @throws IndexOutOfBoundsException + * If index is negative + * or not smaller than the buffer's limit + */ + public abstract $type$ get(int index); + +#if[streamableType] + /** + * Absolute get method. Reads the $type$ at the given + * index without any validation of the index. + * + * @param index + * The index from which the $type$ will be read + * + * @return The $type$ at the given index + */ + abstract $type$ getUnchecked(int index); // package-private +#end[streamableType] + + /** + * Absolute put method (optional operation). + * + *Writes the given $type$ into this buffer at the given + * index.
+ * + * @param index + * The index at which the $type$ will be written + * + * @param $x$ + * The $type$ value to be written + * + * @return This buffer + * + * @throws IndexOutOfBoundsException + * If index is negative + * or not smaller than the buffer's limit + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public abstract $Type$Buffer put(int index, $type$ $x$); + + + // -- Bulk get operations -- + + /** + * Relative bulk get method. + * + *This method transfers $type$s from this buffer into the given + * destination array. If there are fewer $type$s remaining in the + * buffer than are required to satisfy the request, that is, if + * length > remaining(), then no + * $type$s are transferred and a {@link BufferUnderflowException} is + * thrown. + * + *
Otherwise, this method copies length $type$s from this + * buffer into the given array, starting at the current position of this + * buffer and at the given offset in the array. The position of this + * buffer is then incremented by length. + * + *
In other words, an invocation of this method of the form + * src.get(dst, off, len) has exactly the same effect as + * the loop + * + *
{@code
+ * for (int i = off; i < off + len; i++)
+ * dst[i] = src.get():
+ * }
+ *
+ * except that it first checks that there are sufficient $type$s in
+ * this buffer and it is potentially much more efficient.
+ *
+ * @param dst
+ * The array into which $type$s are to be written
+ *
+ * @param offset
+ * The offset within the array of the first $type$ to be
+ * written; must be non-negative and no larger than
+ * dst.length
+ *
+ * @param length
+ * The maximum number of $type$s to be written to the given
+ * array; must be non-negative and no larger than
+ * dst.length - offset
+ *
+ * @return This buffer
+ *
+ * @throws BufferUnderflowException
+ * If there are fewer than length $type$s
+ * remaining in this buffer
+ *
+ * @throws IndexOutOfBoundsException
+ * If the preconditions on the offset and length
+ * parameters do not hold
+ */
+ public $Type$Buffer get($type$[] dst, int offset, int length) {
+ checkBounds(offset, length, dst.length);
+ if (length > remaining())
+ throw new BufferUnderflowException();
+ int end = offset + length;
+ for (int i = offset; i < end; i++)
+ dst[i] = get();
+ return this;
+ }
+
+ /**
+ * Relative bulk get method.
+ *
+ * This method transfers $type$s from this buffer into the given + * destination array. An invocation of this method of the form + * src.get(a) behaves in exactly the same way as the invocation + * + *
+ * src.get(a, 0, a.length)+ * + * @param dst + * The destination array + * + * @return This buffer + * + * @throws BufferUnderflowException + * If there are fewer than length $type$s + * remaining in this buffer + */ + public $Type$Buffer get($type$[] dst) { + return get(dst, 0, dst.length); + } + + + // -- Bulk put operations -- + + /** + * Relative bulk put method (optional operation). + * + *
This method transfers the $type$s remaining in the given source + * buffer into this buffer. If there are more $type$s remaining in the + * source buffer than in this buffer, that is, if + * src.remaining() > remaining(), + * then no $type$s are transferred and a {@link + * BufferOverflowException} is thrown. + * + *
Otherwise, this method copies + * n = src.remaining() $type$s from the given + * buffer into this buffer, starting at each buffer's current position. + * The positions of both buffers are then incremented by n. + * + *
In other words, an invocation of this method of the form + * dst.put(src) has exactly the same effect as the loop + * + *
+ * while (src.hasRemaining()) + * dst.put(src.get());+ * + * except that it first checks that there is sufficient space in this + * buffer and it is potentially much more efficient. + * + * @param src + * The source buffer from which $type$s are to be read; + * must not be this buffer + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * for the remaining $type$s in the source buffer + * + * @throws IllegalArgumentException + * If the source buffer is this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public $Type$Buffer put($Type$Buffer src) { + if (src == this) + throw new IllegalArgumentException(); + if (isReadOnly()) + throw new ReadOnlyBufferException(); + int n = src.remaining(); + if (n > remaining()) + throw new BufferOverflowException(); + for (int i = 0; i < n; i++) + put(src.get()); + return this; + } + + /** + * Relative bulk put method (optional operation). + * + *
This method transfers $type$s into this buffer from the given + * source array. If there are more $type$s to be copied from the array + * than remain in this buffer, that is, if + * length > remaining(), then no + * $type$s are transferred and a {@link BufferOverflowException} is + * thrown. + * + *
Otherwise, this method copies length $type$s from the + * given array into this buffer, starting at the given offset in the array + * and at the current position of this buffer. The position of this buffer + * is then incremented by length. + * + *
In other words, an invocation of this method of the form + * dst.put(src, off, len) has exactly the same effect as + * the loop + * + *
{@code
+ * for (int i = off; i < off + len; i++)
+ * dst.put(a[i]);
+ * }
+ *
+ * except that it first checks that there is sufficient space in this
+ * buffer and it is potentially much more efficient.
+ *
+ * @param src
+ * The array from which $type$s are to be read
+ *
+ * @param offset
+ * The offset within the array of the first $type$ to be read;
+ * must be non-negative and no larger than array.length
+ *
+ * @param length
+ * The number of $type$s to be read from the given array;
+ * must be non-negative and no larger than
+ * array.length - offset
+ *
+ * @return This buffer
+ *
+ * @throws BufferOverflowException
+ * If there is insufficient space in this buffer
+ *
+ * @throws IndexOutOfBoundsException
+ * If the preconditions on the offset and length
+ * parameters do not hold
+ *
+ * @throws ReadOnlyBufferException
+ * If this buffer is read-only
+ */
+ public $Type$Buffer put($type$[] src, int offset, int length) {
+ checkBounds(offset, length, src.length);
+ if (length > remaining())
+ throw new BufferOverflowException();
+ int end = offset + length;
+ for (int i = offset; i < end; i++)
+ this.put(src[i]);
+ return this;
+ }
+
+ /**
+ * Relative bulk put method (optional operation).
+ *
+ * This method transfers the entire content of the given source + * $type$ array into this buffer. An invocation of this method of the + * form dst.put(a) behaves in exactly the same way as the + * invocation + * + *
+ * dst.put(a, 0, a.length)+ * + * @param src + * The source array + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public final $Type$Buffer put($type$[] src) { + return put(src, 0, src.length); + } + +#if[char] + + /** + * Relative bulk put method (optional operation). + * + *
This method transfers $type$s from the given string into this + * buffer. If there are more $type$s to be copied from the string than + * remain in this buffer, that is, if + * end - start > remaining(), + * then no $type$s are transferred and a {@link + * BufferOverflowException} is thrown. + * + *
Otherwise, this method copies + * n = end - start $type$s + * from the given string into this buffer, starting at the given + * start index and at the current position of this buffer. The + * position of this buffer is then incremented by n. + * + *
In other words, an invocation of this method of the form + * dst.put(src, start, end) has exactly the same effect + * as the loop + * + *
{@code
+ * for (int i = start; i < end; i++)
+ * dst.put(src.charAt(i));
+ * }
+ *
+ * except that it first checks that there is sufficient space in this
+ * buffer and it is potentially much more efficient.
+ *
+ * @param src
+ * The string from which $type$s are to be read
+ *
+ * @param start
+ * The offset within the string of the first $type$ to be read;
+ * must be non-negative and no larger than
+ * string.length()
+ *
+ * @param end
+ * The offset within the string of the last $type$ to be read,
+ * plus one; must be non-negative and no larger than
+ * string.length()
+ *
+ * @return This buffer
+ *
+ * @throws BufferOverflowException
+ * If there is insufficient space in this buffer
+ *
+ * @throws IndexOutOfBoundsException
+ * If the preconditions on the start and end
+ * parameters do not hold
+ *
+ * @throws ReadOnlyBufferException
+ * If this buffer is read-only
+ */
+ public $Type$Buffer put(String src, int start, int end) {
+ checkBounds(start, end - start, src.length());
+ if (isReadOnly())
+ throw new ReadOnlyBufferException();
+ if (end - start > remaining())
+ throw new BufferOverflowException();
+ for (int i = start; i < end; i++)
+ this.put(src.charAt(i));
+ return this;
+ }
+
+ /**
+ * Relative bulk put method (optional operation).
+ *
+ * This method transfers the entire content of the given source string + * into this buffer. An invocation of this method of the form + * dst.put(s) behaves in exactly the same way as the invocation + * + *
+ * dst.put(s, 0, s.length())+ * + * @param src + * The source string + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + */ + public final $Type$Buffer put(String src) { + return put(src, 0, src.length()); + } + +#end[char] + + + // -- Other stuff -- + + /** + * Tells whether or not this buffer is backed by an accessible $type$ + * array. + * + *
If this method returns true then the {@link #array() array} + * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. + *
+ * + * @return true if, and only if, this buffer + * is backed by an array and is not read-only + */ + public final boolean hasArray() { + return (hb != null) && !isReadOnly; + } + + /** + * Returns the $type$ array that backs this + * buffer (optional operation). + * + *Modifications to this buffer's content will cause the returned + * array's content to be modified, and vice versa. + * + *
Invoke the {@link #hasArray hasArray} method before invoking this + * method in order to ensure that this buffer has an accessible backing + * array.
+ * + * @return The array that backs this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is backed by an array but is read-only + * + * @throws UnsupportedOperationException + * If this buffer is not backed by an accessible array + */ + public final $type$[] array() { + if (hb == null) + throw new UnsupportedOperationException(); + if (isReadOnly) + throw new ReadOnlyBufferException(); + return hb; + } + + /** + * Returns the offset within this buffer's backing array of the first + * element of the buffer (optional operation). + * + *If this buffer is backed by an array then buffer position p + * corresponds to array index p + arrayOffset(). + * + *
Invoke the {@link #hasArray hasArray} method before invoking this + * method in order to ensure that this buffer has an accessible backing + * array.
+ * + * @return The offset within this buffer's array + * of the first element of the buffer + * + * @throws ReadOnlyBufferException + * If this buffer is backed by an array but is read-only + * + * @throws UnsupportedOperationException + * If this buffer is not backed by an accessible array + */ + public final int arrayOffset() { + if (hb == null) + throw new UnsupportedOperationException(); + if (isReadOnly) + throw new ReadOnlyBufferException(); + return offset; + } + + /** + * Compacts this buffer (optional operation). + * + *The $type$s between the buffer's current position and its limit, + * if any, are copied to the beginning of the buffer. That is, the + * $type$ at index p = position() is copied + * to index zero, the $type$ at index p + 1 is copied + * to index one, and so forth until the $type$ at index + * limit() - 1 is copied to index + * n = limit() - 1 - p. + * The buffer's position is then set to n+1 and its limit is set to + * its capacity. The mark, if defined, is discarded. + * + *
The buffer's position is set to the number of $type$s copied, + * rather than to zero, so that an invocation of this method can be + * followed immediately by an invocation of another relative put + * method.
+ * +#if[byte] + * + *Invoke this method after writing data from a buffer in case the + * write was incomplete. The following loop, for example, copies bytes + * from one channel to another via the buffer buf: + * + *
{@code
+ * buf.clear(); // Prepare buffer for use
+ * while (in.read(buf) >= 0 || buf.position != 0) {
+ * buf.flip();
+ * out.write(buf);
+ * buf.compact(); // In case of partial write
+ * }
+ * }The hash code of a $type$ buffer depends only upon its remaining + * elements; that is, upon the elements from position() up to, and + * including, the element at limit() - 1. + * + *
Because buffer hash codes are content-dependent, it is inadvisable + * to use buffers as keys in hash maps or similar data structures unless it + * is known that their contents will not change.
+ * + * @return The current hash code of this buffer + */ + public int hashCode() { + int h = 1; + int p = position(); + for (int i = limit() - 1; i >= p; i--) +#if[int] + h = 31 * h + get(i); +#else[int] + h = 31 * h + (int)get(i); +#end[int] + return h; + } + + /** + * Tells whether or not this buffer is equal to another object. + * + *Two $type$ buffers are equal if, and only if, + * + *
They have the same element type,
They have the same number of remaining elements, and + *
The two sequences of remaining elements, considered + * independently of their starting positions, are pointwise equal. +#if[floatingPointType] + * This method considers two $type$ elements {@code a} and {@code b} + * to be equal if + * {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}. + * The values {@code -0.0} and {@code +0.0} are considered to be + * equal, unlike {@link $Fulltype$#equals(Object)}. +#end[floatingPointType] + *
A $type$ buffer is not equal to any other type of object.
+ * + * @param ob The object to which this buffer is to be compared + * + * @return true if, and only if, this buffer is equal to the + * given object + */ + public boolean equals(Object ob) { + if (this == ob) + return true; + if (!(ob instanceof $Type$Buffer)) + return false; + $Type$Buffer that = ($Type$Buffer)ob; + if (this.remaining() != that.remaining()) + return false; + int p = this.position(); + for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--) + if (!equals(this.get(i), that.get(j))) + return false; + return true; + } + + private static boolean equals($type$ x, $type$ y) { +#if[floatingPointType] + return (x == y) || ($Fulltype$.isNaN(x) && $Fulltype$.isNaN(y)); +#else[floatingPointType] + return x == y; +#end[floatingPointType] + } + + /** + * Compares this buffer to another. + * + *Two $type$ buffers are compared by comparing their sequences of + * remaining elements lexicographically, without regard to the starting + * position of each sequence within its corresponding buffer. +#if[floatingPointType] + * Pairs of {@code $type$} elements are compared as if by invoking + * {@link $Fulltype$#compare($type$,$type$)}, except that + * {@code -0.0} and {@code 0.0} are considered to be equal. + * {@code $Fulltype$.NaN} is considered by this method to be equal + * to itself and greater than all other {@code $type$} values + * (including {@code $Fulltype$.POSITIVE_INFINITY}). +#else[floatingPointType] + * Pairs of {@code $type$} elements are compared as if by invoking + * {@link $Fulltype$#compare($type$,$type$)}. +#end[floatingPointType] + * + *
A $type$ buffer is not comparable to any other type of object. + * + * @return A negative integer, zero, or a positive integer as this buffer + * is less than, equal to, or greater than the given buffer + */ + public int compareTo($Type$Buffer that) { + int n = this.position() + Math.min(this.remaining(), that.remaining()); + for (int i = this.position(), j = that.position(); i < n; i++, j++) { + int cmp = compare(this.get(i), that.get(j)); + if (cmp != 0) + return cmp; + } + return this.remaining() - that.remaining(); + } + + private static int compare($type$ x, $type$ y) { +#if[floatingPointType] + return ((x < y) ? -1 : + (x > y) ? +1 : + (x == y) ? 0 : + $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1); +#else[floatingPointType] + return $Fulltype$.compare(x, y); +#end[floatingPointType] + } + + // -- Other char stuff -- + +#if[char] + + /** + * Returns a string containing the characters in this buffer. + * + *
The first character of the resulting string will be the character at + * this buffer's position, while the last character will be the character + * at index limit() - 1. Invoking this method does not + * change the buffer's position.
+ * + * @return The specified string + */ + public String toString() { + return toString(position(), limit()); + } + + abstract String toString(int start, int end); // package-private + + + // --- Methods to support CharSequence --- + + /** + * Returns the length of this character buffer. + * + *When viewed as a character sequence, the length of a character + * buffer is simply the number of characters between the position + * (inclusive) and the limit (exclusive); that is, it is equivalent to + * remaining().
+ * + * @return The length of this character buffer + */ + public final int length() { + return remaining(); + } + + /** + * Reads the character at the given index relative to the current + * position. + * + * @param index + * The index of the character to be read, relative to the position; + * must be non-negative and smaller than remaining() + * + * @return The character at index + * position() + index + * + * @throws IndexOutOfBoundsException + * If the preconditions on index do not hold + */ + public final char charAt(int index) { + return get(position() + checkIndex(index, 1)); + } + + /** + * Creates a new character buffer that represents the specified subsequence + * of this buffer, relative to the current position. + * + *The new buffer will share this buffer's content; that is, if the + * content of this buffer is mutable then modifications to one buffer will + * cause the other to be modified. The new buffer's capacity will be that + * of this buffer, its position will be + * position() + start, and its limit will be + * position() + end. The new buffer will be + * direct if, and only if, this buffer is direct, and it will be read-only + * if, and only if, this buffer is read-only.
+ * + * @param start + * The index, relative to the current position, of the first + * character in the subsequence; must be non-negative and no larger + * than remaining() + * + * @param end + * The index, relative to the current position, of the character + * following the last character in the subsequence; must be no + * smaller than start and no larger than + * remaining() + * + * @return The new character buffer + * + * @throws IndexOutOfBoundsException + * If the preconditions on start and end + * do not hold + */ + public abstract CharBuffer subSequence(int start, int end); + + + // --- Methods to support Appendable --- + + /** + * Appends the specified character sequence to this + * buffer (optional operation). + * + *An invocation of this method of the form dst.append(csq) + * behaves in exactly the same way as the invocation + * + *
+ * dst.put(csq.toString())+ * + *
Depending on the specification of toString for the + * character sequence csq, the entire sequence may not be + * appended. For instance, invoking the {@link $Type$Buffer#toString() + * toString} method of a character buffer will return a subsequence whose + * content depends upon the buffer's position and limit. + * + * @param csq + * The character sequence to append. If csq is + * null, then the four characters "null" are + * appended to this character buffer. + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + * + * @since 1.5 + */ + public $Type$Buffer append(CharSequence csq) { + if (csq == null) + return put("null"); + else + return put(csq.toString()); + } + + /** + * Appends a subsequence of the specified character sequence to this + * buffer (optional operation). + * + *
An invocation of this method of the form dst.append(csq, start, + * end) when csq is not null, behaves in exactly the + * same way as the invocation + * + *
+ * dst.put(csq.subSequence(start, end).toString())+ * + * @param csq + * The character sequence from which a subsequence will be + * appended. If csq is null, then characters + * will be appended as if csq contained the four + * characters "null". + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * + * @throws IndexOutOfBoundsException + * If start or end are negative, start + * is greater than end, or end is greater than + * csq.length() + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + * + * @since 1.5 + */ + public $Type$Buffer append(CharSequence csq, int start, int end) { + CharSequence cs = (csq == null ? "null" : csq); + return put(cs.subSequence(start, end).toString()); + } + + /** + * Appends the specified $type$ to this + * buffer (optional operation). + * + *
An invocation of this method of the form dst.append($x$) + * behaves in exactly the same way as the invocation + * + *
+ * dst.put($x$)+ * + * @param $x$ + * The 16-bit $type$ to append + * + * @return This buffer + * + * @throws BufferOverflowException + * If there is insufficient space in this buffer + * + * @throws ReadOnlyBufferException + * If this buffer is read-only + * + * @since 1.5 + */ + public $Type$Buffer append($type$ $x$) { + return put($x$); + } + +#end[char] + + + // -- Other byte stuff: Access to binary data -- + +#if[!byte] + + /** + * Retrieves this buffer's byte order. + * + *
The byte order of $a$ $type$ buffer created by allocation or by + * wrapping an existing $type$ array is the {@link + * ByteOrder#nativeOrder native order} of the underlying + * hardware. The byte order of $a$ $type$ buffer created as a view of a byte buffer is that of the + * byte buffer at the moment that the view is created.
+ * + * @return This buffer's byte order + */ + public abstract ByteOrder order(); + +#end[!byte] + +#if[byte] + + boolean bigEndian // package-private + = true; + boolean nativeByteOrder // package-private + = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN); + + /** + * Retrieves this buffer's byte order. + * + *The byte order is used when reading or writing multibyte values, and + * when creating buffers that are views of this byte buffer. The order of + * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN + * BIG_ENDIAN}.
+ * + * @return This buffer's byte order + */ + public final ByteOrder order() { + return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN; + } + + /** + * Modifies this buffer's byte order. + * + * @param bo + * The new byte order, + * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN} + * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN} + * + * @return This buffer + */ + public final $Type$Buffer order(ByteOrder bo) { + bigEndian = (bo == ByteOrder.BIG_ENDIAN); + nativeByteOrder = + (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN)); + return this; + } + + // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes + // + abstract byte _get(int i); // package-private + abstract void _put(int i, byte b); // package-private + + // #BIN + // + // Binary-data access methods for short, char, int, long, float, + // and double will be inserted here + +#end[byte] + +#if[streamableType] + +#if[char] + @Override +#end[char] + public $Streamtype$Stream $type$s() { + return StreamSupport.$streamtype$Stream(() -> new $Type$BufferSpliterator(this), + Buffer.SPLITERATOR_CHARACTERISTICS, false); + } + +#end[streamableType] + +} diff --git a/out/production/classes1/nio/channels/exceptions b/out/production/classes1/nio/channels/exceptions new file mode 100644 index 0000000000000000000000000000000000000000..3f75fb3fcd2a545d68c317397a7cd48e9b9d6359 --- /dev/null +++ b/out/production/classes1/nio/channels/exceptions @@ -0,0 +1,194 @@ +# +# Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved. +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# This code is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License version 2 only, as +# published by the Free Software Foundation. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA +# or visit www.oracle.com if you need additional information or have any +# questions. +# + +# Generated exception classes for java.nio.channels + +SINCE=1.4 +PACKAGE=java.nio.channels +# This year should only change if the generated source is modified. +COPYRIGHT_YEARS="2000, 2007," + + +SUPER=java.io.IOException + +gen ClosedChannelException " + * Checked exception thrown when an attempt is made to invoke or complete an + * I/O operation upon channel that is closed, or at least closed to that + * operation. That this exception is thrown does not necessarily imply that + * the channel is completely closed. A socket channel whose write half has + * been shut down, for example, may still be open for reading." \ + 882777185433553857L + +gen FileLockInterruptionException " + * Checked exception received by a thread when another thread interrupts it + * while it is waiting to acquire a file lock. Before this exception is thrown + * the interrupt status of the previously-blocked thread will have been set." \ + 7104080643653532383L + + +SUPER=ClosedChannelException + +gen AsynchronousCloseException " + * Checked exception received by a thread when another thread closes the + * channel or the part of the channel upon which it is blocked in an I/O + * operation." \ + 6891178312432313966L + + +SUPER=AsynchronousCloseException + +gen ClosedByInterruptException " + * Checked exception received by a thread when another thread interrupts it + * while it is blocked in an I/O operation upon a channel. Before this + * exception is thrown the channel will have been closed and the interrupt + * status of the previously-blocked thread will have been set." \ + -4488191543534286750L + + +SUPER=IllegalArgumentException + +gen IllegalSelectorException " + * Unchecked exception thrown when an attempt is made to register a channel + * with a selector that was not created by the provider that created the + * channel." \ + -8406323347253320987L + +gen UnresolvedAddressException " + * Unchecked exception thrown when an attempt is made to invoke a network + * operation upon an unresolved socket address." \ + 6136959093620794148L + +gen UnsupportedAddressTypeException " + * Unchecked exception thrown when an attempt is made to bind or connect + * to a socket address of a type that is not supported." \ + -2964323842829700493L + + +SUPER=IllegalStateException + +gen AlreadyConnectedException " + * Unchecked exception thrown when an attempt is made to connect a {@link + * SocketChannel} that is already connected." \ + -7331895245053773357L + +gen ConnectionPendingException " + * Unchecked exception thrown when an attempt is made to connect a {@link + * SocketChannel} for which a non-blocking connection operation is already in + * progress." \ + 2008393366501760879L + +gen ClosedSelectorException " + * Unchecked exception thrown when an attempt is made to invoke an I/O + * operation upon a closed selector." \ + 6466297122317847835L + +gen CancelledKeyException " + * Unchecked exception thrown when an attempt is made to use + * a selection key that is no longer valid." \ + -8438032138028814268L + +gen IllegalBlockingModeException " + * Unchecked exception thrown when a blocking-mode-specific operation + * is invoked upon a channel in the incorrect blocking mode." \ + -3335774961855590474L + +gen NoConnectionPendingException " + * Unchecked exception thrown when the {@link SocketChannel#finishConnect + * finishConnect} method of a {@link SocketChannel} is invoked without first + * successfully invoking its {@link SocketChannel#connect connect} method." \ + -8296561183633134743L + +gen NonReadableChannelException " + * Unchecked exception thrown when an attempt is made to read + * from a channel that was not originally opened for reading." \ + -3200915679294993514L + +gen NonWritableChannelException " + * Unchecked exception thrown when an attempt is made to write + * to a channel that was not originally opened for writing." \ + -7071230488279011621L + +gen NotYetBoundException " + * Unchecked exception thrown when an attempt is made to invoke an I/O + * operation upon a server socket channel that is not yet bound." \ + 4640999303950202242L + +gen NotYetConnectedException " + * Unchecked exception thrown when an attempt is made to invoke an I/O + * operation upon a socket channel that is not yet connected." \ + 4697316551909513464L + +gen OverlappingFileLockException " + * Unchecked exception thrown when an attempt is made to acquire a lock on a + * region of a file that overlaps a region already locked by the same Java + * virtual machine, or when another thread is already waiting to lock an + * overlapping region of the same file." \ + 2047812138163068433L + + +SINCE=1.7 + +SUPER=java.io.IOException + +gen InterruptedByTimeoutException " + * Checked exception received by a thread when a timeout elapses before an + * asynchronous operation completes." \ + -4268008601014042947L + +SUPER=IllegalArgumentException + +gen IllegalChannelGroupException " + * Unchecked exception thrown when an attempt is made to open a channel + * in a group that was not created by the same provider. " \ + -2495041211157744253L + + +SUPER=IllegalStateException + +gen AlreadyBoundException " + * Unchecked exception thrown when an attempt is made to bind the socket a + * network oriented channel that is already bound." \ + 6796072983322737592L + +gen AcceptPendingException " + * Unchecked exception thrown when an attempt is made to initiate an accept + * operation on a channel and a previous accept operation has not completed." \ + 2721339977965416421L + +gen ReadPendingException " + * Unchecked exception thrown when an attempt is made to read from an + * asynchronous socket channel and a previous read has not completed." \ + 1986315242191227217L + +gen WritePendingException " + * Unchecked exception thrown when an attempt is made to write to an + * asynchronous socket channel and a previous write has not completed." \ + 7031871839266032276L + +gen ShutdownChannelGroupException " + * Unchecked exception thrown when an attempt is made to construct a channel in + * a group that is shutdown or the completion handler for an I/O operation + * cannot be invoked because the channel group has terminated." \ + -3903801676350154157L diff --git a/out/production/classes1/nio/channels/spi/package.html b/out/production/classes1/nio/channels/spi/package.html new file mode 100644 index 0000000000000000000000000000000000000000..a6f8cbfdcb32162c2a860cdb911917c9bfaaeaf6 --- /dev/null +++ b/out/production/classes1/nio/channels/spi/package.html @@ -0,0 +1,45 @@ + + + + + + +Service-provider classes for the {@link java.nio.channels} package. + +Only developers who are defining new selector providers or asynchronous +channel providers should need to make direct use of this package.
+ +Unless otherwise noted, passing a null argument to a constructor +or method in any class or interface in this package will cause a {@link +java.lang.NullPointerException NullPointerException} to be thrown. + + +@since 1.4 +@author Mark Reinhold +@author JSR-51 Expert Group + + + diff --git a/out/production/classes1/nio/charset/Charset-X-Coder.java.template b/out/production/classes1/nio/charset/Charset-X-Coder.java.template new file mode 100644 index 0000000000000000000000000000000000000000..f5e50a51c85c3be9ae0553886ac0af1d24a3867e --- /dev/null +++ b/out/production/classes1/nio/charset/Charset-X-Coder.java.template @@ -0,0 +1,996 @@ +/* + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +#warn This file is preprocessed before being compiled + +package java.nio.charset; + +import java.nio.Buffer; +import java.nio.ByteBuffer; +import java.nio.CharBuffer; +import java.nio.BufferOverflowException; +import java.nio.BufferUnderflowException; +import java.lang.ref.WeakReference; +import java.nio.charset.CoderMalfunctionError; // javadoc +import java.util.Arrays; + + +/** + * An engine that can transform a sequence of $itypesPhrase$ into a sequence of + * $otypesPhrase$. + * + * + * + *
The input $itype$ sequence is provided in a $itype$ buffer or a series + * of such buffers. The output $otype$ sequence is written to a $otype$ buffer + * or a series of such buffers. $A$ $coder$ should always be used by making + * the following sequence of method invocations, hereinafter referred to as $a$ + * $coding$ operation: + * + *
Reset the $coder$ via the {@link #reset reset} method, unless it + * has not been used before;
Invoke the {@link #$code$ $code$} 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 {@link #$code$ $code$} method one final time, passing + * true for the endOfInput argument; and then
Invoke the {@link #flush flush} method so that the $coder$ can + * flush any internal state to the output buffer.
There are two general types of $coding$ errors. If the input $itype$ + * sequence is $notLegal$ then the input is considered malformed. If + * the input $itype$ sequence is legal but cannot be mapped to a valid + * $outSequence$ then an unmappable character has been encountered. + * + * + * + *
How $a$ $coding$ error is handled depends upon the action requested for + * that type of error, which is described by an instance of the {@link + * CodingErrorAction} class. The possible error actions are to {@linkplain + * CodingErrorAction#IGNORE ignore} the erroneous input, {@linkplain + * CodingErrorAction#REPORT report} the error to the invoker via + * the returned {@link CoderResult} object, or {@linkplain CodingErrorAction#REPLACE + * replace} the erroneous input with the current value of the + * replacement $replTypeName$. The replacement + * +#if[encoder] + * is initially set to the $coder$'s default replacement, which often + * (but not always) has the initial value $defaultReplName$; +#end[encoder] +#if[decoder] + * has the initial value $defaultReplName$; +#end[decoder] + * + * its value may be changed via the {@link #replaceWith($replFQType$) + * replaceWith} method. + * + *
The default action for malformed-input and unmappable-character errors + * is to {@linkplain CodingErrorAction#REPORT report} them. The + * malformed-input error action may be changed via the {@link + * #onMalformedInput(CodingErrorAction) onMalformedInput} method; the + * unmappable-character action may be changed via the {@link + * #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter} method. + * + *
This class is designed to handle many of the details of the $coding$ + * process, including the implementation of error actions. $A$ $coder$ for a + * specific charset, which is a concrete subclass of this class, need only + * implement the abstract {@link #$code$Loop $code$Loop} method, which + * encapsulates the basic $coding$ loop. A subclass that maintains internal + * state should, additionally, override the {@link #implFlush implFlush} and + * {@link #implReset implReset} methods. + * + *
Instances of this class are not safe for use by multiple concurrent + * threads.
+ * + * + * @author Mark Reinhold + * @author JSR-51 Expert Group + * @since 1.4 + * + * @see ByteBuffer + * @see CharBuffer + * @see Charset + * @see Charset$OtherCoder$ + */ + +public abstract class Charset$Coder$ { + + private final Charset charset; + private final float average$ItypesPerOtype$; + private final float max$ItypesPerOtype$; + + private $replType$ replacement; + private CodingErrorAction malformedInputAction + = CodingErrorAction.REPORT; + private CodingErrorAction unmappableCharacterAction + = CodingErrorAction.REPORT; + + // Internal states + // + private static final int ST_RESET = 0; + private static final int ST_CODING = 1; + private static final int ST_END = 2; + private static final int ST_FLUSHED = 3; + + private int state = ST_RESET; + + private static String stateNames[] + = { "RESET", "CODING", "CODING_END", "FLUSHED" }; + + + /** + * Initializes a new $coder$. The new $coder$ will have the given + * $otypes-per-itype$ and replacement values. + * + * @param cs + * The charset that created this $coder$ + * + * @param average$ItypesPerOtype$ + * A positive float value indicating the expected number of + * $otype$s that will be produced for each input $itype$ + * + * @param max$ItypesPerOtype$ + * A positive float value indicating the maximum number of + * $otype$s that will be produced for each input $itype$ + * + * @param replacement + * The initial replacement; must not be null, must have + * non-zero length, must not be longer than max$ItypesPerOtype$, + * and must be {@linkplain #isLegalReplacement legal} + * + * @throws IllegalArgumentException + * If the preconditions on the parameters do not hold + */ + {#if[encoder]?protected:private} + Charset$Coder$(Charset cs, + float average$ItypesPerOtype$, + float max$ItypesPerOtype$, + $replType$ replacement) + { + this.charset = cs; + if (average$ItypesPerOtype$ <= 0.0f) + throw new IllegalArgumentException("Non-positive " + + "average$ItypesPerOtype$"); + if (max$ItypesPerOtype$ <= 0.0f) + throw new IllegalArgumentException("Non-positive " + + "max$ItypesPerOtype$"); + if (!Charset.atBugLevel("1.4")) { + if (average$ItypesPerOtype$ > max$ItypesPerOtype$) + throw new IllegalArgumentException("average$ItypesPerOtype$" + + " exceeds " + + "max$ItypesPerOtype$"); + } + this.replacement = replacement; + this.average$ItypesPerOtype$ = average$ItypesPerOtype$; + this.max$ItypesPerOtype$ = max$ItypesPerOtype$; + replaceWith(replacement); + } + + /** + * Initializes a new $coder$. The new $coder$ will have the given + * $otypes-per-itype$ values and its replacement will be the + * $replTypeName$ $defaultReplName$. + * + * @param cs + * The charset that created this $coder$ + * + * @param average$ItypesPerOtype$ + * A positive float value indicating the expected number of + * $otype$s that will be produced for each input $itype$ + * + * @param max$ItypesPerOtype$ + * A positive float value indicating the maximum number of + * $otype$s that will be produced for each input $itype$ + * + * @throws IllegalArgumentException + * If the preconditions on the parameters do not hold + */ + protected Charset$Coder$(Charset cs, + float average$ItypesPerOtype$, + float max$ItypesPerOtype$) + { + this(cs, + average$ItypesPerOtype$, max$ItypesPerOtype$, + $defaultRepl$); + } + + /** + * Returns the charset that created this $coder$. + * + * @return This $coder$'s charset + */ + public final Charset charset() { + return charset; + } + + /** + * Returns this $coder$'s replacement value. + * + * @return This $coder$'s current replacement, + * which is never null and is never empty + */ + public final $replType$ replacement() { +#if[decoder] + return replacement; +#end[decoder] +#if[encoder] + return Arrays.copyOf(replacement, replacement.$replLength$); +#end[encoder] + } + + /** + * Changes this $coder$'s replacement value. + * + *This method invokes the {@link #implReplaceWith implReplaceWith} + * method, passing the new replacement, after checking that the new + * replacement is acceptable.
+ * + * @param newReplacement The replacement value + * +#if[decoder] + * The new replacement; must not be null + * and must have non-zero length +#end[decoder] +#if[encoder] + * The new replacement; must not be null, must have + * non-zero length, must not be longer than the value returned by + * the {@link #max$ItypesPerOtype$() max$ItypesPerOtype$} method, and + * must be {@link #isLegalReplacement legal} +#end[encoder] + * + * @return This $coder$ + * + * @throws IllegalArgumentException + * If the preconditions on the parameter do not hold + */ + public final Charset$Coder$ replaceWith($replType$ newReplacement) { + if (newReplacement == null) + throw new IllegalArgumentException("Null replacement"); + int len = newReplacement.$replLength$; + if (len == 0) + throw new IllegalArgumentException("Empty replacement"); + if (len > max$ItypesPerOtype$) + throw new IllegalArgumentException("Replacement too long"); +#if[decoder] + this.replacement = newReplacement; +#end[decoder] +#if[encoder] + if (!isLegalReplacement(newReplacement)) + throw new IllegalArgumentException("Illegal replacement"); + this.replacement = Arrays.copyOf(newReplacement, newReplacement.$replLength$); +#end[encoder] + implReplaceWith(this.replacement); + return this; + } + + /** + * Reports a change to this $coder$'s replacement value. + * + *The default implementation of this method does nothing. This method + * should be overridden by $coder$s that require notification of changes to + * the replacement.
+ * + * @param newReplacement The replacement value + */ + protected void implReplaceWith($replType$ newReplacement) { + } + +#if[encoder] + + private WeakReferenceA replacement is legal if, and only if, it is a legal sequence of + * bytes in this encoder's charset; that is, it must be possible to decode + * the replacement into one or more sixteen-bit Unicode characters. + * + *
The default implementation of this method is not very efficient; it + * should generally be overridden to improve performance.
+ * + * @param repl The byte array to be tested + * + * @return true if, and only if, the given byte array + * is a legal replacement value for this encoder + */ + public boolean isLegalReplacement(byte[] repl) { + WeakReferenceThis method invokes the {@link #implOnMalformedInput + * implOnMalformedInput} method, passing the new action.
+ * + * @param newAction The new action; must not be null + * + * @return This $coder$ + * + * @throws IllegalArgumentException + * If the precondition on the parameter does not hold + */ + public final Charset$Coder$ onMalformedInput(CodingErrorAction newAction) { + if (newAction == null) + throw new IllegalArgumentException("Null action"); + malformedInputAction = newAction; + implOnMalformedInput(newAction); + return this; + } + + /** + * Reports a change to this $coder$'s malformed-input action. + * + *The default implementation of this method does nothing. This method + * should be overridden by $coder$s that require notification of changes to + * the malformed-input action.
+ * + * @param newAction The new action + */ + protected void implOnMalformedInput(CodingErrorAction newAction) { } + + /** + * Returns this $coder$'s current action for unmappable-character errors. + * + * @return The current unmappable-character action, which is never + * null + */ + public CodingErrorAction unmappableCharacterAction() { + return unmappableCharacterAction; + } + + /** + * Changes this $coder$'s action for unmappable-character errors. + * + *This method invokes the {@link #implOnUnmappableCharacter + * implOnUnmappableCharacter} method, passing the new action.
+ * + * @param newAction The new action; must not be null + * + * @return This $coder$ + * + * @throws IllegalArgumentException + * If the precondition on the parameter does not hold + */ + public final Charset$Coder$ onUnmappableCharacter(CodingErrorAction + newAction) + { + if (newAction == null) + throw new IllegalArgumentException("Null action"); + unmappableCharacterAction = newAction; + implOnUnmappableCharacter(newAction); + return this; + } + + /** + * Reports a change to this $coder$'s unmappable-character action. + * + *The default implementation of this method does nothing. This method + * should be overridden by $coder$s that require notification of changes to + * the unmappable-character action.
+ * + * @param newAction The new action + */ + protected void implOnUnmappableCharacter(CodingErrorAction newAction) { } + + /** + * Returns the average number of $otype$s that will be produced for each + * $itype$ of input. This heuristic value may be used to estimate the size + * of the output buffer required for a given input sequence. + * + * @return The average number of $otype$s produced + * per $itype$ of input + */ + public final float average$ItypesPerOtype$() { + return average$ItypesPerOtype$; + } + + /** + * Returns the maximum number of $otype$s that will be produced for each + * $itype$ of input. This value may be used to compute the worst-case size + * of the output buffer required for a given input sequence. + * + * @return The maximum number of $otype$s that will be produced per + * $itype$ of input + */ + public final float max$ItypesPerOtype$() { + return max$ItypesPerOtype$; + } + + /** + * $Code$s as many $itype$s as possible from the given input buffer, + * writing the results to the given output buffer. + * + *The buffers are read from, and written to, starting at their current + * positions. At most {@link Buffer#remaining in.remaining()} $itype$s + * will be read and at most {@link Buffer#remaining out.remaining()} + * $otype$s will be written. The buffers' positions will be advanced to + * reflect the $itype$s read and the $otype$s written, but their marks and + * limits will not be modified. + * + *
In addition to reading $itype$s from the input buffer and writing + * $otype$s to the output buffer, this method returns a {@link CoderResult} + * object to describe its reason for termination: + * + *
{@link CoderResult#UNDERFLOW} indicates that as much of the + * input buffer as possible has been $code$d. If there is no further + * input then the invoker can proceed to the next step of the + * $coding$ operation. Otherwise this method + * should be invoked again with further input.
{@link CoderResult#OVERFLOW} indicates that there is + * insufficient space in the output buffer to $code$ any more $itype$s. + * This method should be invoked again with an output buffer that has + * more {@linkplain Buffer#remaining remaining} $otype$s. This is + * typically done by draining any $code$d $otype$s from the output + * buffer.
A {@linkplain CoderResult#malformedForLength + * malformed-input} result indicates that a malformed-input + * error has been detected. The malformed $itype$s begin at the input + * buffer's (possibly incremented) position; the number of malformed + * $itype$s may be determined by invoking the result object's {@link + * CoderResult#length() length} method. This case applies only if the + * {@linkplain #onMalformedInput malformed action} of this $coder$ + * is {@link CodingErrorAction#REPORT}; otherwise the malformed input + * will be ignored or replaced, as requested.
An {@linkplain CoderResult#unmappableForLength + * unmappable-character} result indicates that an + * unmappable-character error has been detected. The $itype$s that + * $code$ the unmappable character begin at the input buffer's (possibly + * incremented) position; the number of such $itype$s may be determined + * by invoking the result object's {@link CoderResult#length() length} + * method. This case applies only if the {@linkplain #onUnmappableCharacter + * unmappable action} of this $coder$ is {@link + * 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 un$code$d input will be treated + * as being malformed. + * + *
This method works by invoking the {@link #$code$Loop $code$Loop} + * method, interpreting its results, handling error conditions, and + * reinvoking it as necessary.
+ * + * + * @param in + * The input $itype$ buffer + * + * @param out + * The output $otype$ buffer + * + * @param endOfInput + * true if, and only if, the invoker can provide no + * additional input $itype$s beyond those in the given buffer + * + * @return A coder-result object describing the reason for termination + * + * @throws IllegalStateException + * If $a$ $coding$ operation is already in progress and the previous + * step was an invocation neither of the {@link #reset reset} + * method, nor of this method with a value of false for + * the endOfInput parameter, nor of this method with a + * value of true for the endOfInput parameter + * but a return value indicating an incomplete $coding$ operation + * + * @throws CoderMalfunctionError + * If an invocation of the $code$Loop method threw + * an unexpected exception + */ + public final CoderResult $code$($Itype$Buffer in, $Otype$Buffer out, + boolean endOfInput) + { + int newState = endOfInput ? ST_END : ST_CODING; + if ((state != ST_RESET) && (state != ST_CODING) + && !(endOfInput && (state == ST_END))) + throwIllegalStateException(state, newState); + state = newState; + + for (;;) { + + CoderResult cr; + try { + cr = $code$Loop(in, out); + } catch (BufferUnderflowException x) { + throw new CoderMalfunctionError(x); + } catch (BufferOverflowException x) { + throw new CoderMalfunctionError(x); + } + + if (cr.isOverflow()) + return cr; + + if (cr.isUnderflow()) { + if (endOfInput && in.hasRemaining()) { + cr = CoderResult.malformedForLength(in.remaining()); + // Fall through to malformed-input case + } else { + return cr; + } + } + + CodingErrorAction action = null; + if (cr.isMalformed()) + action = malformedInputAction; + else if (cr.isUnmappable()) + action = unmappableCharacterAction; + else + assert false : cr.toString(); + + if (action == CodingErrorAction.REPORT) + return cr; + + if (action == CodingErrorAction.REPLACE) { + if (out.remaining() < replacement.$replLength$) + return CoderResult.OVERFLOW; + out.put(replacement); + } + + if ((action == CodingErrorAction.IGNORE) + || (action == CodingErrorAction.REPLACE)) { + // Skip erroneous input either way + in.position(in.position() + cr.length()); + continue; + } + + assert false; + } + + } + + /** + * Flushes this $coder$. + * + *Some $coder$s maintain internal state and may need to write some + * final $otype$s 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 {@link Buffer#remaining out.remaining()} + * $otype$s 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 {@link + * CoderResult#UNDERFLOW}. If there is insufficient room in the output + * buffer then it returns {@link 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 $coding$ + * operation. + * + *
If this $coder$ has already been flushed then invoking this method + * has no effect. + * + *
This method invokes the {@link #implFlush implFlush} method to + * perform the actual flushing operation.
+ * + * @param out + * The output $otype$ buffer + * + * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or + * {@link CoderResult#OVERFLOW} + * + * @throws IllegalStateException + * If the previous step of the current $coding$ operation was an + * invocation neither of the {@link #flush flush} method nor of + * the three-argument {@link + * #$code$($Itype$Buffer,$Otype$Buffer,boolean) $code$} method + * with a value of true for the endOfInput + * parameter + */ + public final CoderResult flush($Otype$Buffer out) { + if (state == ST_END) { + CoderResult cr = implFlush(out); + if (cr.isUnderflow()) + state = ST_FLUSHED; + return cr; + } + + if (state != ST_FLUSHED) + throwIllegalStateException(state, ST_FLUSHED); + + return CoderResult.UNDERFLOW; // Already flushed + } + + /** + * Flushes this $coder$. + * + *The default implementation of this method does nothing, and always + * returns {@link CoderResult#UNDERFLOW}. This method should be overridden + * by $coder$s that may need to write final $otype$s to the output buffer + * once the entire input sequence has been read.
+ * + * @param out + * The output $otype$ buffer + * + * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or + * {@link CoderResult#OVERFLOW} + */ + protected CoderResult implFlush($Otype$Buffer out) { + return CoderResult.UNDERFLOW; + } + + /** + * Resets this $coder$, clearing any internal state. + * + *This method resets charset-independent state and also invokes the + * {@link #implReset() implReset} method in order to perform any + * charset-specific reset actions.
+ * + * @return This $coder$ + * + */ + public final Charset$Coder$ reset() { + implReset(); + state = ST_RESET; + return this; + } + + /** + * Resets this $coder$, clearing any charset-specific internal state. + * + *The default implementation of this method does nothing. This method + * should be overridden by $coder$s that maintain internal state.
+ */ + protected void implReset() { } + + /** + * $Code$s one or more $itype$s into one or more $otype$s. + * + *This method encapsulates the basic $coding$ loop, $coding$ as many + * $itype$s as possible until it either runs out of input, runs out of room + * in the output buffer, or encounters $a$ $coding$ error. This method is + * invoked by the {@link #$code$ $code$} method, which handles result + * interpretation and error recovery. + * + *
The buffers are read from, and written to, starting at their current + * positions. At most {@link Buffer#remaining in.remaining()} $itype$s + * will be read, and at most {@link Buffer#remaining out.remaining()} + * $otype$s will be written. The buffers' positions will be advanced to + * reflect the $itype$s read and the $otype$s written, but their marks and + * limits will not be modified. + * + *
This method returns a {@link CoderResult} object to describe its + * reason for termination, in the same manner as the {@link #$code$ $code$} + * method. Most implementations of this method will handle $coding$ errors + * by returning an appropriate result object for interpretation by the + * {@link #$code$ $code$} method. An optimized implementation may instead + * examine the relevant error action and implement that action itself. + * + *
An implementation of this method may perform arbitrary lookahead by + * returning {@link CoderResult#UNDERFLOW} until it receives sufficient + * input.
+ * + * @param in + * The input $itype$ buffer + * + * @param out + * The output $otype$ buffer + * + * @return A coder-result object describing the reason for termination + */ + protected abstract CoderResult $code$Loop($Itype$Buffer in, + $Otype$Buffer out); + + /** + * Convenience method that $code$s the remaining content of a single input + * $itype$ buffer into a newly-allocated $otype$ buffer. + * + *This method implements an entire $coding$ + * operation; that is, it resets this $coder$, then it $code$s the + * $itype$s in the given $itype$ buffer, and finally it flushes this + * $coder$. This method should therefore not be invoked if $a$ $coding$ + * operation is already in progress.
+ * + * @param in + * The input $itype$ buffer + * + * @return A newly-allocated $otype$ buffer containing the result of the + * $coding$ operation. The buffer's position will be zero and its + * limit will follow the last $otype$ written. + * + * @throws IllegalStateException + * If $a$ $coding$ operation is already in progress + * + * @throws MalformedInputException + * If the $itype$ sequence starting at the input buffer's current + * position is $notLegal$ and the current malformed-input action + * is {@link CodingErrorAction#REPORT} + * + * @throws UnmappableCharacterException + * If the $itype$ sequence starting at the input buffer's current + * position cannot be mapped to an equivalent $otype$ sequence and + * the current unmappable-character action is {@link + * CodingErrorAction#REPORT} + */ + public final $Otype$Buffer $code$($Itype$Buffer in) + throws CharacterCodingException + { + int n = (int)(in.remaining() * average$ItypesPerOtype$()); + $Otype$Buffer out = $Otype$Buffer.allocate(n); + + if ((n == 0) && (in.remaining() == 0)) + return out; + reset(); + for (;;) { + CoderResult cr = in.hasRemaining() ? + $code$(in, out, true) : CoderResult.UNDERFLOW; + if (cr.isUnderflow()) + cr = flush(out); + + if (cr.isUnderflow()) + break; + if (cr.isOverflow()) { + n = 2*n + 1; // Ensure progress; n might be 0! + $Otype$Buffer o = $Otype$Buffer.allocate(n); + out.flip(); + o.put(out); + out = o; + continue; + } + cr.throwException(); + } + out.flip(); + return out; + } + +#if[decoder] + + /** + * Tells whether or not this decoder implements an auto-detecting charset. + * + *The default implementation of this method always returns + * false; it should be overridden by auto-detecting decoders to + * return true.
+ * + * @return true if, and only if, this decoder implements an + * auto-detecting charset + */ + public boolean isAutoDetecting() { + return false; + } + + /** + * Tells whether or not this decoder has yet detected a + * charset (optional operation). + * + *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 {@link #detectedCharset + * 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 {@link + * UnsupportedOperationException}; it should be overridden by + * auto-detecting decoders to return true once the input charset + * has been determined.
+ * + * @return true if, and only if, this decoder has detected a + * specific charset + * + * @throws UnsupportedOperationException + * If this decoder does not implement an auto-detecting charset + */ + public boolean isCharsetDetected() { + throw new UnsupportedOperationException(); + } + + /** + * Retrieves the charset that was detected by this + * decoder (optional operation). + * + *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 {@link + * IllegalStateException}. + * + *
The default implementation of this method always throws an {@link + * UnsupportedOperationException}; it should be overridden by + * auto-detecting decoders to return the appropriate value.
+ * + * @return The charset detected by this auto-detecting decoder, + * or null if the charset has not yet been determined + * + * @throws IllegalStateException + * If insufficient bytes have been read to determine a charset + * + * @throws UnsupportedOperationException + * If this decoder does not implement an auto-detecting charset + */ + public Charset detectedCharset() { + throw new UnsupportedOperationException(); + } + +#end[decoder] + +#if[encoder] + + private boolean canEncode(CharBuffer cb) { + if (state == ST_FLUSHED) + reset(); + else if (state != ST_RESET) + throwIllegalStateException(state, ST_CODING); + CodingErrorAction ma = malformedInputAction(); + CodingErrorAction ua = unmappableCharacterAction(); + try { + onMalformedInput(CodingErrorAction.REPORT); + onUnmappableCharacter(CodingErrorAction.REPORT); + encode(cb); + } catch (CharacterCodingException x) { + return false; + } finally { + onMalformedInput(ma); + onUnmappableCharacter(ua); + reset(); + } + return true; + } + + /** + * Tells whether or not this encoder can encode the given character. + * + *This method returns false if the given character is a + * surrogate character; such characters can be interpreted only when they + * are members of a pair consisting of a high surrogate followed by a low + * surrogate. The {@link #canEncode(java.lang.CharSequence) + * canEncode(CharSequence)} method may be used to test whether or not a + * character sequence can be encoded. + * + *
This method may modify this encoder's state; it should therefore not + * be invoked if an encoding operation is already in + * progress. + * + *
The default implementation of this method is not very efficient; it + * should generally be overridden to improve performance.
+ * + * @param c + * The given character + * + * @return true if, and only if, this encoder can encode + * the given character + * + * @throws IllegalStateException + * If $a$ $coding$ operation is already in progress + */ + public boolean canEncode(char c) { + CharBuffer cb = CharBuffer.allocate(1); + cb.put(c); + cb.flip(); + return canEncode(cb); + } + + /** + * Tells whether or not this encoder can encode the given character + * sequence. + * + *If this method returns false for a particular character + * sequence then more information about why the sequence cannot be encoded + * may be obtained by performing a full encoding + * operation. + * + *
This method may modify this encoder's state; it should therefore not + * be invoked if an encoding operation is already in progress. + * + *
The default implementation of this method is not very efficient; it + * should generally be overridden to improve performance.
+ * + * @param cs + * The given character sequence + * + * @return true if, and only if, this encoder can encode + * the given character without throwing any exceptions and without + * performing any replacements + * + * @throws IllegalStateException + * If $a$ $coding$ operation is already in progress + */ + public boolean canEncode(CharSequence cs) { + CharBuffer cb; + if (cs instanceof CharBuffer) + cb = ((CharBuffer)cs).duplicate(); + else + cb = CharBuffer.wrap(cs.toString()); + return canEncode(cb); + } + +#end[encoder] + + + private void throwIllegalStateException(int from, int to) { + throw new IllegalStateException("Current state = " + stateNames[from] + + ", new state = " + stateNames[to]); + } + +} diff --git a/out/production/classes1/nio/charset/exceptions b/out/production/classes1/nio/charset/exceptions new file mode 100644 index 0000000000000000000000000000000000000000..22dfa3ca621d9539e7abbe05d119f99265033822 --- /dev/null +++ b/out/production/classes1/nio/charset/exceptions @@ -0,0 +1,53 @@ +# +# Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved. +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# This code is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License version 2 only, as +# published by the Free Software Foundation. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA +# or visit www.oracle.com if you need additional information or have any +# questions. +# + +# Generated exception classes for java.nio.charset + +SINCE=1.4 +PACKAGE=java.nio.charset +# This year should only change if the generated source is modified. +COPYRIGHT_YEARS="2000, 2007," + +SUPER=java.io.IOException + +gen CharacterCodingException " + * Checked exception thrown when a character encoding + * or decoding error occurs." \ + 8421532232154627783L + + +SUPER=IllegalArgumentException + +gen IllegalCharsetNameException " + * Unchecked exception thrown when a string that is not a + * legal charset name is used as such." \ + 1457525358470002989L \ + String charsetName CharsetName "illegal charset name" + +gen UnsupportedCharsetException " + * Unchecked exception thrown when no support is available + * for a requested charset." \ + 1490765524727386367L \ + String charsetName CharsetName "name of the unsupported charset" diff --git a/out/production/classes1/nio/charset/package.html b/out/production/classes1/nio/charset/package.html new file mode 100644 index 0000000000000000000000000000000000000000..69b160b81391d26dbc633351b63a3037262b8b29 --- /dev/null +++ b/out/production/classes1/nio/charset/package.html @@ -0,0 +1,88 @@ + + + + + + + +Defines charsets, decoders, and encoders, for translating between bytes and +Unicode characters. + ++ ++
+ Class name
Description
+ {@link java.nio.charset.Charset} +A named mapping between characters
and bytes+ {@link java.nio.charset.CharsetDecoder} +Decodes bytes into characters + {@link java.nio.charset.CharsetEncoder} +Encodes characters into bytes + {@link java.nio.charset.CoderResult} +Describes coder results + + {@link java.nio.charset.CodingErrorAction} +Describes actions to take when
coding errors are detected
A charset is named mapping between sequences of sixteen-bit Unicode +characters and sequences of bytes, in the sense defined in RFC 2278. A +decoder is an engine which transforms bytes in a specific charset into +characters, and an encoder is an engine which transforms characters into +bytes. Encoders and decoders operate on byte and character buffers. They are +collectively referred to as coders. + +
The {@link java.nio.charset.Charset} class defines methods for creating +coders for a given charset and for retrieving the various names associated with +a charset. It also defines static methods for testing whether a particular +charset is supported, for locating charset instances by name, and for +constructing a map that contains every charset for which support is available +in the current Java virtual machine. + +
Most users will not use these classes directly; instead they will use the +existing charset-related constructors and methods in the {@link +java.lang.String} class, together with the existing {@link +java.io.InputStreamReader} and {@link java.io.OutputStreamWriter} classes, all +of whose implementations have been reworked to make use of the charset +facilities defined in this package. A small number of changes have been made +to the {@link java.io.InputStreamReader} and {@link java.io.OutputStreamWriter} +classes in order to allow explicit charset objects to be specified in the +construction of instances of those classes. + +
Support for new charsets can be made available via the interface defined in +the {@link java.nio.charset.spi.CharsetProvider} class in the {@link +java.nio.charset.spi} package. + +
Unless otherwise noted, passing a null argument to a constructor +or method in any class or interface in this package will cause a {@link +java.lang.NullPointerException NullPointerException} to be thrown. + + +@since 1.4 +@author Mark Reinhold +@author JSR-51 Expert Group + + + diff --git a/out/production/classes1/nio/charset/spi/package.html b/out/production/classes1/nio/charset/spi/package.html new file mode 100644 index 0000000000000000000000000000000000000000..a7b7ab1887902f45ce68b8e1784001b2bbd1d9f3 --- /dev/null +++ b/out/production/classes1/nio/charset/spi/package.html @@ -0,0 +1,45 @@ + + + + +
+ +Service-provider classes for the {@link java.nio.charset} package. + +Only developers who are defining new charsets should need to make direct +use of this package.
+ +Unless otherwise noted, passing a null argument to a constructor +or method in any class or interface in this package will cause a {@link +java.lang.NullPointerException NullPointerException} to be thrown. + + +@since 1.4 +@author Mark Reinhold +@author JSR-51 Expert Group + + + diff --git a/out/production/classes1/nio/exceptions b/out/production/classes1/nio/exceptions new file mode 100644 index 0000000000000000000000000000000000000000..062ccc4e438d5bd3f891beecb13e5acc449f4b28 --- /dev/null +++ b/out/production/classes1/nio/exceptions @@ -0,0 +1,60 @@ +# +# Copyright (c) 2000, 2007, Oracle and/or its affiliates. All rights reserved. +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# This code is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License version 2 only, as +# published by the Free Software Foundation. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA +# or visit www.oracle.com if you need additional information or have any +# questions. +# + +# Generated exception classes for java.nio + +SINCE=1.4 +PACKAGE=java.nio +# This year should only change if the generated source is modified. +COPYRIGHT_YEARS="2000, 2007," + + +SUPER=RuntimeException + +gen BufferOverflowException " + * Unchecked exception thrown when a relative put operation reaches + * the target buffer's limit." \ + -5484897634319144535L + +gen BufferUnderflowException " + * Unchecked exception thrown when a relative get operation reaches + * the source buffer's limit." \ + -1713313658691622206L + + +SUPER=IllegalStateException + +gen InvalidMarkException " + * Unchecked exception thrown when an attempt is made to reset a buffer + * when its mark is not defined." \ + 1698329710438510774L + + +SUPER=UnsupportedOperationException + +gen ReadOnlyBufferException " + * Unchecked exception thrown when a content-mutation method such as + * put or compact is invoked upon a read-only buffer." \ + -1210063976496234090L diff --git a/out/production/classes1/nio/package.html b/out/production/classes1/nio/package.html new file mode 100644 index 0000000000000000000000000000000000000000..eddd611a1c78978cc817e959cd7fe9d05a7643ef --- /dev/null +++ b/out/production/classes1/nio/package.html @@ -0,0 +1,139 @@ + + + + +
+ +Defines buffers, which are containers for data, and provides an overview of the +other NIO packages. + + +The central abstractions of the NIO APIs are:
+ +Buffers, which are containers for data; +
Charsets and their
+ associated decoders and encoders,
which translate between
+ bytes and Unicode characters;
Channels of
+ various types, which represent connections
to entities capable of
+ performing I/O operations; and
Selectors and selection keys, which together with
+ selectable channels define a multiplexed, non-blocking
+ I/O facility.
The java.nio package defines the buffer classes, which are used +throughout the NIO APIs. The charset API is defined in the {@link +java.nio.charset} package, and the channel and selector APIs are defined in the +{@link java.nio.channels} package. Each of these subpackages has its own +service-provider (SPI) subpackage, the contents of which can be used to extend +the platform's default implementations or to construct alternative +implementations. + + + + +
+ ++
+ Buffers
Description
+ {@link java.nio.Buffer} +Position, limit, and capacity; +
clear, flip, rewind, and mark/reset+ {@link java.nio.ByteBuffer} +Get/put, compact, views; allocate, wrap + {@link java.nio.MappedByteBuffer} +A byte buffer mapped to a file + {@link java.nio.CharBuffer} +Get/put, compact; allocate, wrap + {@link java.nio.DoubleBuffer} +' ' + {@link java.nio.FloatBuffer} +' ' + {@link java.nio.IntBuffer} +' ' + {@link java.nio.LongBuffer} +' ' + {@link java.nio.ShortBuffer} +' ' + {@link java.nio.ByteOrder} +Typesafe enumeration for byte orders
A buffer is a container for a fixed amount of data of a specific +primitive type. In addition to its content a buffer has a position, +which is the index of the next element to be read or written, and a +limit, which is the index of the first element that should not be read +or written. The base {@link java.nio.Buffer} class defines these properties as +well as methods for clearing, flipping, and rewinding, for +marking the current position, and for resetting the position to +the previous mark. + +
There is a buffer class for each non-boolean primitive type. Each class +defines a family of get and put methods for moving data out of +and in to a buffer, methods for compacting, duplicating, and +slicing a buffer, and static methods for allocating a new buffer +as well as for wrapping an existing array into a buffer. + +
Byte buffers are distinguished in that they can be used as the sources and +targets of I/O operations. They also support several features not found in the +other buffer classes: + +
A byte buffer can be allocated as a + direct buffer, in which case the Java virtual machine will make a + best effort to perform native I/O operations directly upon it.
A byte buffer can be created by {@link + java.nio.channels.FileChannel#map mapping} a region of a + file directly into memory, in which case a few additional file-related + operations defined in the {@link java.nio.MappedByteBuffer} class are + available.
A byte buffer provides access to its content as either a heterogeneous + or homogeneous sequence of binary data + of any non-boolean primitive type, in either big-endian or little-endian byte order.
Unless otherwise noted, passing a null argument to a constructor +or method in any class or interface in this package will cause a {@link +java.lang.NullPointerException NullPointerException} to be thrown. + +@since 1.4 +@author Mark Reinhold +@author JSR-51 Expert Group + + + diff --git a/out/production/classes1/rmi/activation/package.html b/out/production/classes1/rmi/activation/package.html new file mode 100644 index 0000000000000000000000000000000000000000..ed4bb79bffe6022cd01492f82bd287ab60a69390 --- /dev/null +++ b/out/production/classes1/rmi/activation/package.html @@ -0,0 +1,61 @@ + + + + +
+ +Provides support for RMI Object Activation. A remote +object's reference can be made ``persistent'' and later activated into a +``live'' object using the RMI activation mechanism. + +Implementations are not required to support the activation +mechanism. If activation is not supported by this implementation, +several specific activation API methods are all required to throw +{@code UnsupportedOperationException}. If activation is supported by this +implementation, these methods must never throw {@code +UnsupportedOperationException}. These methods are denoted by the +presence of an entry for {@code UnsupportedOperationException} in the +Throws section of each method's specification. + + + +@since 1.2 + + diff --git a/out/production/classes1/rmi/dgc/package.html b/out/production/classes1/rmi/dgc/package.html new file mode 100644 index 0000000000000000000000000000000000000000..a1b63b6a6b84c3dea9131020f463b06ca5620d46 --- /dev/null +++ b/out/production/classes1/rmi/dgc/package.html @@ -0,0 +1,55 @@ + + + + +
+ +Provides classes and interface for RMI distributed +garbage-collection (DGC). When the RMI server returns an object to +its client (caller of the remote method), it tracks the remote +object's usage in the client. When there are no more references to the +remote object on the client, or if the reference's ``lease'' expires and +not renewed, the server garbage-collects the remote object. + + + +@since JDK1.1 + + diff --git a/out/production/classes1/rmi/package.html b/out/production/classes1/rmi/package.html new file mode 100644 index 0000000000000000000000000000000000000000..1551d1b919d703534e255c62d6efd854b626fc37 --- /dev/null +++ b/out/production/classes1/rmi/package.html @@ -0,0 +1,59 @@ + + + + + + +Provides the RMI package. RMI is Remote Method Invocation. It is a +mechanism that enables an object on one Java virtual machine to invoke +methods on an object in another Java virtual machine. Any object that +can be invoked this way must implement the Remote interface. When such +an object is invoked, its arguments are ``marshalled'' and sent from the +local virtual machine to the remote one, where the arguments are +``unmarshalled.'' When the method terminates, the results are +marshalled from the remote machine and sent to the caller's virtual +machine. If the method invocation results in an exception being +thrown, the exception is indicated to caller. + + + +@since JDK1.1 + + diff --git a/out/production/classes1/rmi/registry/package.html b/out/production/classes1/rmi/registry/package.html new file mode 100644 index 0000000000000000000000000000000000000000..2451d22702eb8fa45915354cc495e4eb9488514e --- /dev/null +++ b/out/production/classes1/rmi/registry/package.html @@ -0,0 +1,57 @@ + + + + + + + +Provides a class and two interfaces for the RMI registry. +A registry is a remote object that maps names to remote objects. A +server registers its remote objects with the registry so that they can +be looked up. When an object wants to invoke a method on a remote +object, it must first lookup the remote object using its name. The +registry returns to the calling object a reference to the remote +object, using which a remote method can be invoked. + + + +@since JDK1.1 + +